image-js 1.0.0-alpha.2 → 1.0.0

package/src/geometry/transform.ts

@@ -1,61 +1,177 @@
-import { inverse, Matrix } from 'ml-matrix';
+import { Matrix, inverse } from 'ml-matrix';
 
-import { Image } from '../Image';
-import { getInterpolationFunction } from '../utils/interpolatePixel';
-import { InterpolationType, BorderType } from '../types';
+import { Image } from '../Image.js';
+import { getClamp } from '../utils/clamp.js';
+import type { BorderType } from '../utils/interpolateBorder.js';
+import { getBorderInterpolation } from '../utils/interpolateBorder.js';
+import type { InterpolationType } from '../utils/interpolatePixel.js';
+import { getInterpolationFunction } from '../utils/interpolatePixel.js';
 
-interface ITransformOptions {
+export interface TransformOptions {
+  /**
+   * Width of the output image.
+   */
   width?: number;
+  /**
+   * Height of the output image.
+   */
   height?: number;
+  /**
+   * Method to use to interpolate the new pixels.
+   * @default `'bilinear'`
+   */
+
   interpolationType?: InterpolationType;
+  /**
+   * Specify how the borders should be handled.
+   * @default `'constant'`
+   */
   borderType?: BorderType;
-  inverse?: boolean;
+  /**
+   * Value of the border if BorderType is 'constant'.
+   *  @default `0`
+   */
   borderValue?: number;
+  /**
+   * Whether the transform matrix should be inverted.
+   */
+  inverse?: boolean;
+  /**
+   * Bypasses width and height options to include
+   * every pixel of the original image inside the transformed image.
+   */
+  fullImage?: boolean;
 }
 
+/**
+ * Transforms an image using a matrix.
+ * @param image - Original image.
+ * @param transformMatrix - 2×3 transform matrix.
+ * @param options - Transform options.
+ * @returns The new image.
+ */
 export function transform(
   image: Image,
-  transform: number[][],
-  options: ITransformOptions = {}
+  transformMatrix: number[][],
+  options: TransformOptions = {},
 ): Image {
-  const width = options.width || image.width;
-  const height = options.height || image.height;
-  const borderType = options.borderType || BorderType.CONSTANT;
-  const borderValue = options.borderValue || 0;
-  const interpolationType =
-    options.interpolationType || InterpolationType.NEAREST;
-  if (
-    transform.length !== 2 ||
-    transform[0].length !== 3 ||
-    transform[1].length !== 3
-  ) {
-    throw new Error(
-      `transformation matrix must be 2x3, found ${transform.length}x${
-        transform[0].length
-      }`
+  const {
+    borderType = 'constant',
+    borderValue = 0,
+    interpolationType = 'bilinear',
+    fullImage,
+  } = options;
+  let { width = image.width, height = image.height } = options;
+
+  if (!isValidMatrix(transformMatrix)) {
+    throw new TypeError(
+      `transformation matrix must be 2x3 or 3x3. Received ${transformMatrix.length}x${transformMatrix[1].length}`,
     );
   }
+  if (transformMatrix.length === 2) {
+    transformMatrix.push([0, 0, 1]);
+  }
+
+  if (fullImage) {
+    transformMatrix = transformMatrix.map((row) => row.slice());
+    transformMatrix[0][2] = 0;
+    transformMatrix[1][2] = 0;
+    const corners = [
+      image.getCoordinates('top-left'),
+      image.getCoordinates('top-right'),
+      image.getCoordinates('bottom-right'),
+      image.getCoordinates('bottom-left'),
+    ];
+
+    corners[1].column += 1;
+    corners[2].column += 1;
+    corners[2].row += 1;
+    corners[3].row += 1;
+
+    const transformedCorners = corners.map((corner) => {
+      return [
+        transformPoint(
+          transformMatrix[0],
+          transformMatrix[2],
+          corner.column,
+          corner.row,
+        ),
+        transformPoint(
+          transformMatrix[1],
+          transformMatrix[2],
+          corner.column,
+          corner.row,
+        ),
+      ];
+    });
+
+    const xCoordinates = transformedCorners.map((c) => c[0]);
+    const yCoordinates = transformedCorners.map((c) => c[1]);
+    const maxX = Math.max(...xCoordinates);
+    const maxY = Math.max(...yCoordinates);
+    const minX = Math.min(...xCoordinates);
+    const minY = Math.min(...yCoordinates);
+    const center = [(image.width - 1) / 2, (image.height - 1) / 2];
+
+    width = maxX - minX;
+    height = maxY - minY;
+
+    const centerX = transformPoint(
+      transformMatrix[0],
+      transformMatrix[2],
+      center[0],
+      center[1],
+    );
+    const centerY = transformPoint(
+      transformMatrix[1],
+      transformMatrix[2],
+      center[0],
+      center[1],
+    );
+    const a = (width - 1) / 2 - centerX;
+    const b = (height - 1) / 2 - centerY;
+    transformMatrix[0][2] = a;
+    transformMatrix[1][2] = b;
+    width = Math.round(width);
+    height = Math.round(height);
+  }
 
   if (!options.inverse) {
-    transform = [transform[0], transform[1], [0, 0, 1]];
-    transform = inverse(new Matrix(transform)).to2DArray();
+    transformMatrix = inverse(new Matrix(transformMatrix)).to2DArray();
   }
   const newImage = Image.createFrom(image, {
     width,
-    height
+    height,
   });
 
+  const interpolateBorder = getBorderInterpolation(borderType, borderValue);
+  const clamp = getClamp(newImage);
+
   const interpolate = getInterpolationFunction(interpolationType);
-  const hFactor = newImage.width * newImage.channels;
-  for (let y = 0; y < newImage.height; y++) {
-    const hOffset = hFactor * y;
-    for (let x = 0; x < newImage.width; x++) {
-      const wOffset = hOffset + x * image.channels;
-      const nx = transformPointX(transform, x, y);
-      const ny = transformPointY(transform, x, y);
-      for (let c = 0; c < newImage.channels; c++) {
-        const newValue = interpolate(image, nx, ny, c, borderType, borderValue);
-        newImage.data[wOffset + c] = newValue;
+  for (let row = 0; row < newImage.height; row++) {
+    for (let column = 0; column < newImage.width; column++) {
+      const nx = transformPoint(
+        transformMatrix[0],
+        transformMatrix[2],
+        column,
+        row,
+      );
+      const ny = transformPoint(
+        transformMatrix[1],
+        transformMatrix[2],
+        column,
+        row,
+      );
+      for (let channel = 0; channel < newImage.channels; channel++) {
+        const newValue = interpolate(
+          image,
+          nx,
+          ny,
+          channel,
+          interpolateBorder,
+          clamp,
+        );
+        newImage.setValue(column, row, channel, newValue);
       }
     }
   }
@@ -63,10 +179,34 @@ export function transform(
   return newImage;
 }
 
-function transformPointX(transform: number[][], x: number, y: number): number {
-  return transform[0][0] * x + transform[0][1] * y + transform[0][2];
+/**
+ * Apply a transformation to a point.
+ * @param transform - Transformation matrix.
+ * @param perspective - Perspective matrix.
+ * @param column - Column of the point.
+ * @param row - Row of the point.
+ * @returns New value.
+ */
+function transformPoint(
+  transform: number[],
+  perspective: number[],
+  column: number,
+  row: number,
+): number {
+  return (
+    (transform[0] * column + transform[1] * row + transform[2]) /
+    (perspective[0] * column + perspective[1] * row + perspective[2])
+  );
 }
 
-function transformPointY(transform: number[][], x: number, y: number): number {
-  return transform[1][0] * x + transform[1][1] * y + transform[1][2];
+function isValidMatrix(transformationMatrix: number[][]) {
+  return (
+    (transformationMatrix.length === 3 &&
+      transformationMatrix[0].length === 3 &&
+      transformationMatrix[1].length === 3 &&
+      transformationMatrix[2].length === 3) ||
+    (transformationMatrix.length === 2 &&
+      transformationMatrix[0].length === 3 &&
+      transformationMatrix[1].length === 3)
+  );
 }

package/src/geometry/transformRotate.ts

@@ -0,0 +1,65 @@
+import type { Image, ImageCoordinates } from '../Image.js';
+import type { Point } from '../utils/geometry/points.js';
+
+import type { TransformOptions } from './transform.js';
+import { transform } from './transform.js';
+
+export interface TransformRotateOptions extends TransformOptions {
+  /**
+   * Specify the rotation center point as a predefined string or a Point.
+   * @default `'center'`.
+   */
+  center?: ImageCoordinates | Point;
+  /**
+   * Scaling factor for the rotated image.
+   *  @default `1`
+   */
+  scale?: number;
+}
+
+/**
+ * Rotate an image anti-clockwise of a given angle.
+ * @param image - Original image.
+ * @param angle - Angle in degrees.
+ * @param options - Rotate options.
+ * @returns A new rotated image.
+ */
+export function transformRotate(
+  image: Image,
+  angle: number,
+  options: TransformRotateOptions = {},
+): Image {
+  const { center = 'center', scale = 1, ...otherOptions } = options;
+
+  let centerCoordinates;
+  if (typeof center === 'string') {
+    centerCoordinates = image.getCoordinates(center);
+  } else {
+    centerCoordinates = center;
+  }
+  const transformMatrix = getRotationMatrix(angle, centerCoordinates, scale);
+
+  return transform(image, transformMatrix, otherOptions);
+}
+
+/**
+ * Generates a rotation matrix for the given angle.
+ * @param angle - Angle in degrees.
+ * @param center - Center point of the image.
+ * @param scale - Scaling factor.
+ * @returns 3 x 3 rotation matrix.
+ */
+function getRotationMatrix(
+  angle: number,
+  center: Point,
+  scale: number,
+): number[][] {
+  const angleRadians = (angle * Math.PI) / 180;
+  const cos = scale * Math.cos(angleRadians);
+  const sin = scale * Math.sin(angleRadians);
+  return [
+    [cos, sin, (1 - cos) * center.column - sin * center.row],
+    [-sin, cos, sin * center.column + (1 - cos) * center.row],
+    [0, 0, 1],
+  ];
+}

package/src/index.ts

@@ -1,8 +1,24 @@
-export * from './Image';
-export * from './compute';
-export * from './filters';
-export * from './load';
-export * from './operations';
-export * from './geometry';
-export * from './save';
-export * from './types';
+export * from './align/index.js';
+export * from './compare/index.js';
+export * from './compute/index.js';
+export * from './correctColor/index.js';
+export * from './draw/index.js';
+export * from './featureMatching/index.js';
+export * from './filters/index.js';
+export * from './geometry/index.js';
+export * from './utils/geometry/index.js';
+export * from './Image.js';
+export * from './load/index.js';
+export * from './Mask.js';
+export * from './maskAnalysis/index.js';
+export * from './morphology/index.js';
+export * from './operations/index.js';
+export * from './roi/index.js';
+export * from './save/index.js';
+export * from './Stack.js';
+export { decodeStack } from './stack/load/decodeStack.js';
+export * from './utils/utils.types.js';
+export * from './utils/constants/channelLabels.js';
+export * from './utils/constants/colorModels.js';
+export { BorderType } from './utils/interpolateBorder.js';
+export { InterpolationType } from './utils/interpolatePixel.js';

package/src/load/decode.ts

@@ -1,28 +1,30 @@
-import { Image } from '../Image';
+import imageType from 'image-type';
+import { match } from 'ts-pattern';
 
-import checkHeader from './checkHeader';
-import { decodePng } from './decodePng';
-import { decodeJpeg } from './decodeJpeg';
+import type { Image } from '../Image.js';
 
-const pngHeader = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
-const jpegHeader = [0xff, 0xd8, 0xff];
+import { decodeJpeg } from './decodeJpeg.js';
+import { decodePng } from './decodePng.js';
+import { decodeTiff } from './decodeTiff.js';
 
 /**
  * Decode input data. Data format is automatically detected.
- * Possible formats: png and jpeg.
- * @param data - data to decode
+ * Possible formats: png, jpeg and tiff.
+ * @param data - Data to decode.
+ * @returns The decoded image.
  */
 export function decode(data: ArrayBufferView): Image {
   const typedArray = new Uint8Array(
     data.buffer,
     data.byteOffset,
-    data.byteLength
+    data.byteLength,
   );
-  if (checkHeader(typedArray, pngHeader)) {
-    return decodePng(typedArray);
-  } else if (checkHeader(typedArray, jpegHeader)) {
-    return decodeJpeg(typedArray);
-  } else {
-    throw new Error('unrecognized data format');
-  }
+  const type = imageType(typedArray);
+  return match(type)
+    .with({ mime: 'image/png' }, () => decodePng(typedArray))
+    .with({ mime: 'image/jpeg' }, () => decodeJpeg(typedArray))
+    .with({ mime: 'image/tiff' }, () => decodeTiff(typedArray))
+    .otherwise(() => {
+      throw new RangeError(`invalid data format: ${type?.mime}`);
+    });
 }

package/src/load/decodeJpeg.ts

@@ -1,15 +1,31 @@
+import { decode as decodeExif } from 'fast-jpeg';
 import { decode } from 'jpeg-js';
 
-import { Image, ImageKind } from '../Image';
+import { Image } from '../Image.js';
+
+import { getMetadata } from './getMetadata.js';
 
 /**
  * Decode a jpeg. See the jpeg-js npm module.
- * @param buffer The data to decode
+ * @param buffer - The data to decode.
+ * @returns The decoded image.
  */
 export function decodeJpeg(buffer: Uint8Array): Image {
-  const jpeg = decode(buffer, true);
+  const jpeg = decode(buffer, {
+    useTArray: true,
+    maxMemoryUsageInMB: Number.POSITIVE_INFINITY,
+    maxResolutionInMP: Number.POSITIVE_INFINITY,
+  });
+
+  const decodedExif = decodeExif(buffer);
+  // TODO : handle stacks (many IFDs?)
+  const meta = decodedExif.exif?.[0]
+    ? getMetadata(decodedExif.exif[0])
+    : undefined;
+
   return new Image(jpeg.width, jpeg.height, {
     data: jpeg.data,
-    kind: ImageKind.RGBA
+    colorModel: 'RGBA',
+    meta,
   });
 }

package/src/load/decodePng.ts

@@ -1,58 +1,61 @@
-import { decode, IDecodedPNG } from 'fast-png';
+import type { DecodedPng } from 'fast-png';
+import { decode } from 'fast-png';
 
-import { Image, ImageKind, ColorDepth } from '../Image';
+import type { BitDepth } from '../Image.js';
+import { Image } from '../Image.js';
+import type { ImageColorModel } from '../utils/constants/colorModels.js';
+import { assert } from '../utils/validators/assert.js';
 
 /**
- * Decode a png. See the fast-png npm module.
- * @param buffer The data to decode
+ * Decode a PNG. See the fast-png npm module.
+ * @param buffer - The data to decode.
+ * @returns The decoded image.
  */
 export function decodePng(buffer: Uint8Array): Image {
   const png = decode(buffer);
 
-  let kind: ImageKind;
-  const depth: ColorDepth =
-    png.depth === 16 ? ColorDepth.UINT16 : ColorDepth.UINT8;
+  let colorModel: ImageColorModel;
+  const bitDepth: BitDepth = png.depth === 16 ? 16 : 8;
 
   if (png.palette) {
-    return loadPalettePNG(png);
+    return loadPalettePng(png);
   }
 
   switch (png.channels) {
     case 1:
-      kind = ImageKind.GREY;
+      colorModel = 'GREY';
       break;
     case 2:
-      kind = ImageKind.GREYA;
+      colorModel = 'GREYA';
       break;
     case 3:
-      kind = ImageKind.RGB;
+      colorModel = 'RGB';
       break;
     case 4:
-      kind = ImageKind.RGBA;
+      colorModel = 'RGBA';
       break;
     default:
-      throw new Error(`Unexpected number of channels: ${png.channels}`);
+      throw new RangeError(`invalid number of channels: ${png.channels}`);
   }
-  return new Image({
-    width: png.width,
-    height: png.height,
-    kind,
-    depth,
-    data: png.data
+  return new Image(png.width, png.height, {
+    colorModel,
+    bitDepth,
+    data: png.data,
   });
 }
 
-function loadPalettePNG(png: IDecodedPNG): Image {
-  if (!png.palette) {
-    throw new Error(
-      'unexpected: there should be a palette when colourType is 3'
-    );
-  }
+/**
+ * Compute PNG data from palette information and return a new image.
+ * @param png - Decoded PNG.
+ * @returns The new image.
+ */
+function loadPalettePng(png: DecodedPng): Image {
+  assert(png.palette);
   const pixels = png.width * png.height;
   const data = new Uint8Array(pixels * 3);
   const pixelsPerByte = 8 / png.depth;
   const factor = png.depth < 8 ? pixelsPerByte : 1;
-  const mask = parseInt('1'.repeat(png.depth), 2);
+  const mask = Number.parseInt('1'.repeat(png.depth), 2);
   let dataIndex = 0;
 
   for (let i = 0; i < pixels; i++) {
@@ -70,6 +73,6 @@ function loadPalettePNG(png: IDecodedPNG): Image {
   }
 
   return new Image(png.width, png.height, {
-    data
+    data,
   });
 }

package/src/load/decodeTiff.ts

@@ -0,0 +1,63 @@
+import { decode } from 'tiff';
+
+import type { BitDepth } from '../Image.js';
+import { Image } from '../Image.js';
+
+import { getMetadata } from './getMetadata.js';
+
+type TiffIfd = ReturnType<typeof decode>[number];
+
+/**
+ * Decode a TIFF. See the tiff module.
+ * @param buffer - The data to decode.
+ * @returns The decoded image.
+ */
+export function decodeTiff(buffer: Uint8Array): Image {
+  const result = decode(buffer);
+  return getImageFromIFD(result[0]);
+  // TODO: optimize not to decode whole file
+}
+
+/**
+ * Create image from a single IFD.
+ * @param ifd - The IFD.
+ * @returns The decoded image.
+ */
+export function getImageFromIFD(ifd: TiffIfd): Image {
+  if (ifd.type === 3) {
+    // Palette
+    const data = new Uint16Array(3 * ifd.width * ifd.height);
+    const palette = ifd.palette as Array<[number, number, number]>;
+    let ptr = 0;
+    for (const index of ifd.data) {
+      const color = palette[index];
+      data[ptr++] = color[0];
+      data[ptr++] = color[1];
+      data[ptr++] = color[2];
+    }
+    return new Image(ifd.width, ifd.height, {
+      data,
+      // TODO: handle alpha properly
+      colorModel: ifd.alpha ? 'RGBA' : 'RGB',
+      // TODO: handle other bit depths
+      bitDepth: 16,
+      meta: getMetadata(ifd),
+    });
+  } else {
+    return new Image(ifd.width, ifd.height, {
+      // TODO: handle float data
+      // @ts-expect-error float data not handled yet
+      data: ifd.data,
+      bitDepth: ifd.bitsPerSample as BitDepth,
+      colorModel:
+        ifd.type === 2
+          ? ifd.alpha
+            ? 'RGBA'
+            : 'RGB'
+          : ifd.alpha
+            ? 'GREYA'
+            : 'GREY',
+      meta: getMetadata(ifd),
+    });
+  }
+}

package/src/load/fetchURL.ts

@@ -0,0 +1,13 @@
+import { decode } from './decode.js';
+
+/**
+ * Fetches image URL and decodes it.
+ * @param dataUrl - Image URL.
+ * @returns decoded image data.
+ */
+export async function fetchURL(dataUrl: string) {
+  const response = await fetch(dataUrl);
+  const arrayBuffer = await response.arrayBuffer();
+  const image = decode(new DataView(arrayBuffer));
+  return image;
+}

package/src/load/getMetadata.ts

@@ -0,0 +1,18 @@
+import type { decode } from 'tiff';
+
+type TiffIfd = ReturnType<typeof decode>[number];
+
+/**
+ * Get metadata from an IFD.
+ * @param ifd - The IFD.
+ * @returns The metadata.
+ */
+export function getMetadata(ifd: TiffIfd) {
+  return {
+    tiff: {
+      fields: ifd.fields,
+      tags: ifd.map,
+    },
+    exif: ifd.exif as unknown as Record<string, unknown>,
+  };
+}

package/src/load/index.ts

@@ -1,6 +1,9 @@
-export * from './decode';
-export * from './decodeJpeg';
-export * from './decodePng';
-export * from './read';
-export * from './readCanvas';
-export * from './readImg';
+export * from './decode.js';
+export * from './decodeJpeg.js';
+export * from './decodePng.js';
+export * from './decodeTiff.js';
+export * from './load.types.js';
+export * from './read.js';
+export * from './readCanvas.js';
+export * from './readImg.js';
+export * from './fetchURL.js';

package/src/load/load.types.ts

@@ -0,0 +1,7 @@
+export interface ImageMetadata {
+  tiff: {
+    fields: Map<number, unknown>;
+    tags: Record<string, unknown>;
+  };
+  exif: Record<string, unknown>;
+}