fvtt-types/src/foundry/client/helpers/media/image-helper.d.mts

TypeScript type definitions for Foundry VTT

import type { Identity, InexactPartial, ValueOf } from "#utils";
import type FilePicker from "#client/applications/apps/file-picker.mjs";

/**
 * A helper class to provide common functionality for working with Image objects
 */
declare class ImageHelper {
  /**
   * Create thumbnail preview for a provided image path.
   * @param src     - The string URL or DisplayObject of the texture to render to a thumbnail
   * @param options - Additional named options passed to the {@linkcode ImageHelper.compositeCanvasTexture} method (default: `{}`)
   * @returns The parsed and converted thumbnail data
   */
  static createThumbnail(
    src: string | PIXI.DisplayObject,
    options?: ImageHelper.CreateThumbnailOptions,
  ): Promise<ImageHelper.ThumbnailReturn | null>;

  /**
   * Test whether a source file has a supported image extension type
   * @param src - A requested image source path
   * @returns Does the filename end with a valid image extension?
   */
  static hasImageExtension(src: string): boolean;

  /**
   * Composite a canvas object by rendering it to a single texture
   * @param object  - The DisplayObject to render to a texture
   * @param options - Additional named options (default: `{}`)
   * @returns The composite Texture object
   */
  static compositeCanvasTexture(object: PIXI.DisplayObject, options?: ImageHelper.CompositeOptions): PIXI.Texture;

  /**
   * Extract a texture to a base64 PNG string
   * @param texture - The Texture object to extract
   * @param options - (default: `{}`)
   * @returns A base64 png string of the texture
   */
  static textureToImage(texture: PIXI.Texture, options?: ImageHelper.TextureToImageOptions): Promise<string>;

  /**
   * Asynchronously convert a DisplayObject container to base64 using Canvas#toBlob and FileReader
   * @param target  - A PIXI display object to convert
   * @param type    - The requested mime type of the output, default is image/png
   * @param quality - A number between 0 and 1 for image quality if image/jpeg or image/webp
   * @returns A processed base64 string
   * @privateRemarks Foundry doesn't mark `type` or `quality` as optional, but they're passed directly to `this.canvasToBase64`, where they *are* optional.
   */
  static pixiToBase64(
    target: PIXI.DisplayObject,
    type?: ImageHelper.IMAGE_MIME_TYPES,
    quality?: number,
  ): Promise<string>;

  /**
   * Asynchronously convert a canvas element to base64.
   * @param type    - (default: `"image/png"`)
   * @param quality - JPEG or WEBP compression from 0 to 1. Default is 0.92.
   * @returns The base64 string of the canvas.
   */
  static canvasToBase64(
    canvas: HTMLCanvasElement,
    type?: ImageHelper.IMAGE_MIME_TYPES,
    quality?: number,
  ): Promise<string>;

  /**
   * Upload a base64 image string to a persisted data storage location
   * @param base64   - The base64 string
   * @param fileName - The file name to upload
   * @param filePath - The file path where the file should be uploaded
   * @param options  - Additional options which affect uploading
   * @returns A promise which resolves to the FilePicker upload response
   */
  static uploadBase64(
    base64: string,
    fileName: string,
    filePath: string,
    options?: ImageHelper.UploadBase64Options,
  ): Promise<FilePicker.UploadReturn>;

  /**
   * Create a canvas element containing the pixel data.
   * @param pixels - Buffer used to create the image data.
   * @param width  - Buffered image width.
   * @param height - Buffered image height.
   */
  static pixelsToCanvas(
    pixels: Uint8ClampedArray,
    width: number,
    height: number,
    options?: ImageHelper.PixelsToCanvasOptions,
  ): HTMLCanvasElement;
}

declare namespace ImageHelper {
  interface Any extends AnyImageHelper {}
  interface AnyConstructor extends Identity<typeof AnyImageHelper> {}

  type IMAGE_MIME_TYPES = ValueOf<typeof CONST.IMAGE_FILE_EXTENSIONS>;

  /** @internal */
  type _CompositeOptions = InexactPartial<{
    /**
     * Center the texture in the rendered frame?
     * @defaultValue `true`
     */
    center: boolean;

    /**
     * The desired height of the output texture
     * @defaultValue The height of the object passed to {@linkcode ImageHelper.compositeCanvasTexture}
     */
    height: number;

    /**
     * A horizontal translation to apply to the object
     * @defaultValue `0`
     */
    tx: number;

    /**
     * A vertical translation to apply to the object
     * @defaultValue `0`
     */
    ty: number;

    /**
     * The desired width of the output texture
     * @defaultValue The width of the object passed to {@linkcode ImageHelper.compositeCanvasTexture}
     */
    width: number;
  }>;

  /**
   * An interface for options for the {@linkcode ImageHelper.createThumbnail} and {@linkcode ImageHelper.compositeCanvasTexture}
   * methods.
   */
  interface CompositeOptions extends _CompositeOptions {}

  interface CreateThumbnailOptions extends CompositeOptions, TextureToImageOptions {}

  /** @internal */
  type _TextureToImageOptions = InexactPartial<{
    /**
     * Image format, e.g. "image/jpeg" or "image/webp".
     * @defaultValue `"image/png"`
     */
    format: IMAGE_MIME_TYPES;

    /**
     * JPEG or WEBP compression from 0 to 1. Default is 0.92.
     * @defaultValue `0.92`
     */
    quality: number;
  }>;

  interface TextureToImageOptions extends _TextureToImageOptions {}

  /** @internal */
  type _UploadBase64Options = InexactPartial<{
    /**
     * The data storage location to which the file should be uploaded
     * @defaultValue `"data"`
     */
    storage: FilePicker.SourceType;

    /**
     * The MIME type of the file being uploaded
     * @remarks Will be extracted from the base64 data, if not provided.
     */
    type: IMAGE_MIME_TYPES;

    /**
     * Display a UI notification when the upload is processed.
     * @defaultValue `true`
     */
    notify: boolean;
  }>;

  interface UploadBase64Options extends _UploadBase64Options {}

  /**
   * An interface for return values of the {@linkcode ImageHelper.createThumbnail} method.
   */
  interface ThumbnailReturn {
    /**
     * The height of the {@linkcode PIXI.Sprite}, created by {@linkcode ImageHelper.createThumbnail}
     */
    height: number;

    /**
     * The originally passed `string` URL or DisplayObject
     */
    src: string | PIXI.DisplayObject;

    /**
     * The Texture, returned from {@linkcode ImageHelper.compositeCanvasTexture}, with `destroy(true)` already called on it.
     */
    texture: PIXI.Texture;

    /**
     * The base64 encoded image data, returned from {@linkcode ImageHelper.textureToImage}
     */
    thumb: string;

    /**
     * The width of the {@linkcode PIXI.Sprite}, created by {@linkcode ImageHelper.createThumbnail}
     */
    width: number;
  }

  type _PixelsToCanvasOptions = InexactPartial<{
    /**
     * The element to use.
     * @remarks If not provided, a new HTMLCanvasElement is created.
     */
    element: HTMLCanvasElement;

    /** Specified width for the element (default to buffer image width). */
    ew: number;

    /** Specified height for the element (default to buffer image height). */
    eh: number;
  }>;

  interface PixelsToCanvasOptions extends _PixelsToCanvasOptions {}
}

export default ImageHelper;

declare abstract class AnyImageHelper extends ImageHelper {
  constructor(...args: never);
}