immutable-app-image

Immutable App Image is an Immutable App module that provides image upload, editing and storage functionality.

Immutable App Image uses Cropper.js to crop images on the client side prior to uploading and sharp to process images on the backend.

Images are stored via an mz/fs compatible file system which can be the local file system or a remote virtual file system such as gcsfs.

Immutable App Image uses Immutable Core Service to persist image type and image profile data globally. This data is used whenever images are displayed or uploaded. By default this data will be refreshed every 60 seconds so changes to image types and image profiles will not be reflected by application clients for up to 60 seconds.

Immutable App Image v0.3 and Immutable Core Model v3

Immutable App Image v0.3 is required to support the breaking changes that were made in Immutable Core Model v3.

Immutable App Image v0.3 is not compatible with Imutable Core Model v2.

Image Schema

Image

Property name | Description | ----------------|--------------------------------------------------------------| fileName | string param case file name will have id and type appended | fileType | string encoding type (jpg|png|webp) | imageName | string user provided name for description | imageTypeId | id for Image Type | meta | object user provided meta data for image | path | string location of image in file system |

The Image model stores basic information about the original image uploaded by the user.

The fileName of the image is constructed from the param-case name, the Image id and the fileType.

For example: if the user provided name is "My Vacation" the fileName might be: "my-vacation-8449328a1eedfd27b1214d7d4fb16315.jpg".

The path of the image is relative to the base of the file system and does not include the fileName.

The meta data for an image can include anything. In the meta data lat and 'lng' should be used as the properties for geo location, title should be used for a single line description of the image, description should be used for a longer multi-line description of the image, and createTime should be used to store the datetime when the image was originally taken.

Image Type

Property name | Description | ----------------|--------------------------------------------------------------| cropClient | string crop image on client (always|best|never) | fileType | string encoding type (jpg|png|webp) | height | integer image height | imageTypeName | string image type name | maxClientHeight | integer maximum image height to upload from client | maxClientWidth | integer maximum image width to upload from client | maxHeight | integer maximum image height | maxWidth | integer maximum image width | quality | integer 0-100 quality for jpg and webp image encoding | width | integer image width |

Image Types are used for categorizing images and defined how images are uploaded and stored.

The clientCrop parameter determines whether or not cropping and encoding will be done by the client.

By default clientCrop is set to best which means that the image will only be cropped by the client if it exceeds the maxClientHeight or maxClientWidth values.

Cropping on the client will reduce upload times for large images but that may come at the price of reduced image quality.

The fileType determines how the file will be stored on the server.

If maxHeight and/or maxWidth properties are set they will limit the size of the image but aspect ratio will be maintained and the image will not be upscaled if it is less than the maxHeight/maxWidth.

If height and/or width are set the image will the scaled to exactly these values. Image may be upscaled and aspect ratio may not be maintained.

Image Profile

Property name | Description | ----------------|--------------------------------------------------------------| fileType | string encoding type (jpg|png|webp) | height | integer image height | imageProfileName| string image profile name | maxHeight | integer maximum image height | maxWidth | integer maximum image width | pregenerate | boolean generate images for for profile in advance | quality | integer 0-100 quality for jpg and webp image encoding | width | integer image width |

Image Profiles define different versions of an image that will be made available for download.

One or more Image Profiles can be linked to an Image Type.

The name for a profile must be in param case: i.e. lower case, dashes, and no spaces.

If the pregenerate property is set then when an image is uploaded a version of for the Image Profile will be created.

Pre-generated images are stored with the profile name afer the id and before the fileType like: "my-vacation-8449328a1eedfd27b1214d7d4fb16315-thumbnail.jpg".

To support webp multiple profiles with the same name should be created. One of these profiles should be either jpg or png and the either should be webp.