/** The raster formats this module recognizes and can prepare for embedding. */
export type ImageFormat = 'jpeg' | 'png' | 'jpeg2000' | 'gif' | 'tiff' | 'bmp';
/**
 * Sniff the raster format from a file's leading magic bytes (JPEG SOI, the PNG
 * signature, or a JP2 box / raw JPEG 2000 codestream). Returns the
 * {@link ImageFormat}, or `null` when none matches.
 */
export declare function detectImageFormat(bytes: Uint8Array): ImageFormat | null;
/**
 * The same picture with one colour knocked out of it, as a PNG.
 *
 * A picture may name a colour it is drawn WITHOUT — MS-ODRAW's
 * `pictureTransparent`, DrawingML's `a:clrChange` to nothing — which is how
 * clip art of the pre-alpha age says "this rectangle of ground is not part of
 * the drawing". It is a property of the USE, not of the file, so it is baked
 * here into bytes of its own: two shapes may knock different colours out of the
 * same blip, and a resource store that hashes content then keeps them apart by
 * itself.
 *
 * 23884's satellite sits on a red field and its globe on a white one; drawn as
 * stored, they are a red block and a white square on a blue slide.
 *
 * @param bytes The picture, in any format {@link prepareImage} reads.
 * @param hex   The colour to knock out, 6-hex and no leading `#`.
 * @returns A PNG with that colour transparent, or `undefined` when the picture
 *   cannot be decoded to samples this can work on.
 */
export declare function knockOutColor(bytes: Uint8Array, hex: string): Uint8Array | undefined;
/** Options controlling how {@link prepareImage} emits an image. */
export interface EmbedImageOptions {
    /**
     * PDF/A-1 forbids transparency (soft masks). When true, PNG alpha is
     * composited onto an opaque white background and no `/SMask` is emitted.
     */
    readonly flattenAlpha?: boolean;
}
/**
 * The ready-to-emit result of decoding and validating one image, from the
 * prepare/add split (oop-design §3.1): {@link prepareImage} is the pure expert —
 * decode, validate (throws on unsupported/corrupt input) and produce the
 * stream bytes; `addImage` only creates the PDF objects. Layout probes with
 * `prepareImage` (no throwaway document), the emit phase replays the prepared
 * result, and other writers (SVG) reuse the mime/dimensions.
 */
export interface PreparedImage {
    readonly format: ImageFormat;
    readonly mimeType: 'image/jp2' | 'image/jpeg' | 'image/png' | 'image/gif' | 'image/tiff' | 'image/bmp';
    readonly widthPx: number;
    readonly heightPx: number;
    /**
     * ColorSpace/BitsPerComponent are absent for JPEG 2000 (carried inside the
     * JPX codestream).
     */
    readonly colorSpace?: 'DeviceGray' | 'DeviceRGB';
    readonly bitsPerComponent?: number;
    /** The PDF stream filter the `data` bytes are encoded with. */
    readonly filter: 'DCTDecode' | 'FlateDecode' | 'JPXDecode';
    readonly data: Uint8Array;
    /** PNG alpha channel, already FlateDecode-compressed (DeviceGray, 8 bpc). */
    readonly smaskData?: Uint8Array;
    /**
     * The resolution the picture states for itself, in pixels per inch, when it
     * states one (JFIF's `Xdensity`/`Ydensity`, PNG's `pHYs`). It is what makes a
     * picture's NATURAL size: 800 pixels at 300 dpi is 192 points wide, not the
     * 600 the 96-dpi default would give. Absent ⇒ the reader's own default.
     */
    readonly dpiX?: number;
    readonly dpiY?: number;
}
/**
 * Decode and validate one image into a {@link PreparedImage} ready to embed.
 * JPEG and JPEG 2000 pass through verbatim (readers decode them); PNG is
 * inflated, de-filtered and re-compressed, splitting any alpha into a soft mask.
 *
 * @throws Error when the format is unrecognized, unsupported, or corrupt.
 */
export declare function prepareImage(bytes: Uint8Array, options?: EmbedImageOptions): PreparedImage;