@metools/web-image-converter 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+interface CompressionOptions {
+    format: string;
+    quality?: number;
+}
+declare abstract class ImageCompressionOptions {
+    abstract get optionExport(): CompressionOptions;
+}
+declare class JpegCompressionOptions extends ImageCompressionOptions {
+    quality: number;
+    constructor(quality: number);
+    get optionExport(): CompressionOptions;
+}
+declare class PngCompressionOptions extends ImageCompressionOptions {
+    quality: number;
+    constructor(quality: number);
+    get optionExport(): CompressionOptions;
+}
+declare class GifCompressionOptions extends ImageCompressionOptions {
+    get optionExport(): CompressionOptions;
+}
+declare class BmpCompressionOptions extends ImageCompressionOptions {
+    get optionExport(): CompressionOptions;
+}
+declare class TgaCompressionOptions extends ImageCompressionOptions {
+    get optionExport(): CompressionOptions;
+}
+declare class TiffCompressionOptions extends ImageCompressionOptions {
+    get optionExport(): CompressionOptions;
+}
+
+interface CropDimensionOptions {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface CropAspectRatioOptions {
+    ratio_width: number;
+    ratio_height: number;
+}
+interface CropEachSideOptions {
+    crop_left: number;
+    crop_right: number;
+    crop_top: number;
+    crop_bottom: number;
+}
+type CropOptions = CropDimensionOptions | CropAspectRatioOptions | CropEachSideOptions;
+declare abstract class ImageCropOptions {
+    abstract get optionExport(): CropOptions;
+}
+declare class ImageCropDimensionOptions extends ImageCropOptions {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    constructor(payload: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    });
+    get optionExport(): CropDimensionOptions;
+}
+declare class ImageCropAspectRatioOptions extends ImageCropOptions {
+    ratio_width: number;
+    ratio_height: number;
+    constructor(payload: {
+        ratio_width: number;
+        ratio_height: number;
+    });
+    get optionExport(): CropAspectRatioOptions;
+}
+declare class ImageCropEachSideOptions extends ImageCropOptions {
+    crop_left: number;
+    crop_right: number;
+    crop_top: number;
+    crop_bottom: number;
+    constructor(payload: {
+        crop_left: number;
+        crop_right: number;
+        crop_top: number;
+        crop_bottom: number;
+    });
+    get optionExport(): CropEachSideOptions;
+}
+
+interface ResizeDimensionOptions {
+    width: number;
+    height: number;
+}
+interface ResizeAspectRatioOptions {
+    ratio_width: number;
+    ratio_height: number;
+}
+interface ResizeLongestSideOptions {
+    longest_side: number;
+}
+type ResizeOptions = ResizeDimensionOptions | ResizeAspectRatioOptions | ResizeLongestSideOptions;
+declare abstract class ImpageResizeOptions {
+    abstract get optionExport(): ResizeOptions;
+}
+declare class ImageResizeDimensionOptions extends ImpageResizeOptions {
+    width: number;
+    height: number;
+    constructor(payload: {
+        width: number;
+        height: number;
+    });
+    get optionExport(): ResizeDimensionOptions;
+}
+declare class ImageResizeAspectRatioOptions extends ImpageResizeOptions {
+    ratio_width: number;
+    ratio_height: number;
+    constructor(payload: {
+        ratio_width: number;
+        ratio_height: number;
+    });
+    get optionExport(): ResizeAspectRatioOptions;
+}
+declare class ImageResizeLongestSideOptions extends ImpageResizeOptions {
+    longest_side: number;
+    constructor(payload: {
+        longest_side: number;
+    });
+    get optionExport(): ResizeLongestSideOptions;
+}
+
+interface ImageConverterInput {
+    compression?: ImageCompressionOptions;
+    resize?: ImpageResizeOptions;
+    crop?: ImageCropOptions;
+}
+declare class ImageConverter {
+    compression?: ImageCompressionOptions;
+    resize?: ImpageResizeOptions;
+    crop?: ImageCropOptions;
+    constructor(payload: ImageConverterInput);
+    get options(): Record<string, unknown>;
+    convertImageFile(file: File): Promise<Uint8Array<ArrayBufferLike>>;
+    convertImageBytes(bytes: Uint8Array): Promise<Uint8Array<ArrayBufferLike>>;
+}
+
+declare function getJpegConverter(payload?: {
+    quality?: number;
+    longest_side?: number;
+}): ImageConverter;
+
+declare function getPngConverter(payload?: {
+    compressionLevel?: number;
+    longest_side?: number;
+}): ImageConverter;
+
+export { BmpCompressionOptions, GifCompressionOptions, ImageConverter, ImageCropAspectRatioOptions, ImageCropDimensionOptions, ImageCropEachSideOptions, ImageResizeAspectRatioOptions, ImageResizeDimensionOptions, ImageResizeLongestSideOptions, JpegCompressionOptions, PngCompressionOptions, TgaCompressionOptions, TiffCompressionOptions, getJpegConverter, getPngConverter };

package/dist/index.js

@@ -451,17 +451,17 @@ var JpegCompressionOptions = class extends ImageCompressionOptions {
   }
 };
 var PngCompressionOptions = class extends ImageCompressionOptions {
-  constructor(compressionLevel) {
+  constructor(quality) {
     super();
-    if (compressionLevel < 0 || compressionLevel > 9) {
+    if (quality < 0 || quality > 9) {
       throw new Error("Compression level must be between 0 and 9");
     }
-    this.compressionLevel = compressionLevel;
+    this.quality = quality;
   }
   get optionExport() {
     return {
       format: "png",
-      quality: this.compressionLevel
+      quality: this.quality
     };
   }
 };

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "@metools/web-image-converter",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": [
-    "dist/image_converter_back_end_bg.wasm"
-  ],
   "type": "module",
   "sideEffects": false,
   "author": "Mathew E. Thompson",

package/readme.md

@@ -0,0 +1,181 @@
+# @metools/web-image-converter
+
+### An image-converter for use on the web, written in Rust.
+
+Ever had a really large image that you wanted to compress quickly?
+
+Do users upload enormous 20 megapixel photos to your website?
+
+Do you want to cut down on file uploads and compute on your servers?
+
+This package is for you!
+
+@metools/web-image-converter is a web-compatible package for converting images. It has basic operations for resizing, cropping and compressing images. It can read from and convert to the following formats:
+
+- Jpeg
+- Png
+- Gif
+- Bmp
+- Targa/Tga
+- Tiff
+
+The meat of the project is written in Rust and exported into a WebAssembly binary. The project also contains a TypeScript API for interacting with the WebAssembly back end.
+
+## Usage
+
+The project uses a set of classes for a declarative approach to converting images. The project is based around the ImageConverter class and several option classes that can be used.
+
+The ImageConverter class can be used with either a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) object or a [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) representing the binary data of an image file.
+
+Example usage:
+
+```ts
+function convertMyImage(file: File) {
+  // Creates a basic image converter
+  const converter = new ImageConverter();
+  // Converts a JS File object and returns a Uint8Array
+  const result = await converter.convertImageFile(file);
+  // Afterward, you can do what you want with this byte array,
+  // such as streaming it to a server via a Form Post or make
+  // a Blob and download it with URL.createObjectURL
+  return result;
+}
+```
+
+`ImageConverter` provides two different ways to convert images:
+
+- `convertImageFile(file: File): Promise<Uint8Array<ArrayBufferLike>>`
+  - This API accepts a JavaScript File object and runs it through the process
+- `convertImageBytes(bytes: Uint8Array): Promise<Uint8Array<ArrayBufferLike>>`
+  - This API accepts a Uint8Array and does the same thing as `convertImageFile`.
+
+Both APIs return a `Uint8Array` object that can be used in any place where you may want to stream or save files:
+
+- [MDN Sending and Receiving Binary Data](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest_API/Sending_and_Receiving_Binary_Data)
+- [MDN createObjectURL](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL_static)
+- [MDN Using object URLs to display images](https://developer.mozilla.org/en-US/docs/Web/API/File_API/Using_files_from_web_applications#example_using_object_urls_to_display_images)
+
+### Options
+
+You can specify one of several `CompressionOptions` objects to represent output format and compression:
+
+- `JpegCompressionOptions(quality: number)`
+  - Quality represents JPEG image quality. Should be a number between 1-100
+- `PngCompressionOptions(quality: number)`
+  - Quality represents PNG image quality. Quality above 75 uses `Best` compression and everything else uses `Fast` compression
+- `GifCompressionOptions()`
+- `BmpCompressionOptions()`
+- `TgaCompressionOptions()`
+- `TiffCompressionOptions()`
+
+You can specify one of several `ResizeOptions` objects to represent resizing an image:
+
+- `ImageResizeLongestSideOptions(payload: { longest_side: number; })`
+  - This operation will find the longest side and resize that side to the provided number. This operation will preserve the aspect ratio.
+- `ImageResizeDimensionOptions(payload: { width: number; height: number; })`
+  - This will resize the image to the specified width and height. This operation will not preserve the image's aspect ratio and may cause squishing or stretching
+- `ImageResizeAspectRatioOptions(payload: { ratio_width: number; ratio_height: number; })`
+  - This operation will resize the image to a specific aspect ratio. This operation may cause squishing or stretching
+
+You can specify one of serveral `CropOptions` objects to represent cropping an image:
+
+- `ImageCropDimensionOptions(payload: { x: number; y: number; width: number; height: number; })`
+  - This operation sets the x and y position, then defines the width and height of a new image. This operation allows you to defined a sub-picture within the larger picture.
+- `ImageCropAspectRatioOptions(payload: { ratio_width: number; ratio_height: number; })`
+  - This operation allows you to define a new aspect ratio for an image and crops the image in the center based on this aspect ratio. E.g. you can use 1 for both `ratio_width` and `ratio_height` to define a square and crop a square in the middle of the image
+- `ImageCropEachSideOptions(payload: { crop_left: number; crop_right: number; crop_top: number; crop_bottom: number; })`
+  - This operation allows you to describe cropping pixels on each of the four sides of the image.
+
+### Errors
+
+When the files and binary data provided conform to the file specs of the above supported image formats, the project should work fine. However, if the data provided is NOT an image, `convertImageFile` and `convertImageBytes` will each throw an error. The function should be wrapped in a try / catch block to catch errors.
+
+### Blocking Operation
+
+Running an operation via WebAssmebly is a blocking operation. This means that when the operation is called, it will block a wide variety of tasks in the application from continuing to run, such as UI operations, timers, etc. For instance, when compressing a large image from a DSLR camera, it may take several seconds for the operation to complete and during that time everything else freezes.
+
+As such, web workers may be a beneficial to put this operation into a web worker for the sake of leaving the main thread open to other operations:
+
+[MDN Using Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers)
+
+## Examples
+
+Converting a file to Jpeg:
+
+```ts
+function makeMyFileAJpeg(file: File) {
+  // Jpeg compression is set to 60. Decent middle ground for
+  // quality and size
+  const converter = new ImageConverter({
+    compression: new JpegCompressionOptions(60),
+  });
+
+  const result = await converter.convertImageFile(file);
+}
+```
+
+Creating a PNG file:
+
+```ts
+function makeMyFileAPng(file: File) {
+  // Jpeg compression is set to 60. Decent middle ground for
+  // quality and size
+  const converter = new ImageConverter({
+    compression: new PngCompressionOptions(60),
+  });
+
+  const result = await converter.convertImageFile(file);
+}
+```
+
+Using several converters to make several different files:
+
+```ts
+function makeImageSet(bin: Uint8Array) {
+  const thumb = new ImageConverter({
+    compression: new JpegCompressionOptions(40),
+    resize: new ImageResizeLongestSideOptions({
+      longest_side: 128,
+    }),
+  });
+  const preview = new ImageConverter({
+    compression: new JpegCompressionOptions(40),
+    resize: new ImageResizeLongestSideOptions({
+      longest_side: 256,
+    }),
+  });
+  const image = new ImageConverter({
+    compression: new JpegCompressionOptions(60),
+    resize: new ImageResizeLongestSideOptions({
+      longest_side: 1280,
+    }),
+  });
+
+  const [thumbResult, previewResult, imageResult] = Promise.all([
+    thumb.convertImageBytes(bin),
+    preview.convertImageBytes(bin),
+    image.convertImageBytes(bin),
+  ]);
+
+  // Do what you want
+}
+```
+
+Cropping an image to a square and resizing for a profile pic
+
+```ts
+function makeProfilePic(file: File) {
+  const profile = new ImageConverter({
+    compression: new JpegCompressionOptions(40),
+    crop: new ImageCropAspectRatioOptions({
+      ratio_width: 1,
+      ratio_height: 1,
+    }),
+    resize: new ImageResizeLongestSideOptions({
+      longest_side: 128,
+    }),
+  });
+
+  const result = await profile.convertImageFile(file);
+}
+```