product-photo

Background removal, alpha trim, and background compositing with procedural shadow synthesis for product photography.

What it does

@takazudo/zudo-image-tweaker/product-photo builds a product-photography pipeline out of three steps: ML background removal, transparent-padding trim, and compositing the cutout onto a background canvas — optionally with synthesized drop shadows so a flat cutout reads as sitting on (or floating above) a surface.

Exports

function removeBackground(input: ImageInput | URL): Promise<Buffer>;
function alphaTrim(input: ImageInput, options?: AlphaTrimOptions): Promise<Buffer>;
function composeProductPhoto(
  subject: ImageInput,
  options: ComposeProductPhotoOptions,
): Promise<ComposeProductPhotoResult>;
function generateShadowLayers(
  alphaImage: string | Buffer,
  options?: GenerateShadowLayersOptions,
): Promise<ShadowLayer[]>;

type ImageInput = string | Buffer;

• removeBackground — segments the subject out of its background, returning an RGBA PNG buffer. See Optional peer dependency below.

• alphaTrim — crops fully-transparent padding down to the opaque/semi-opaque content of an image with an alpha channel.

• composeProductPhoto — the compositor: fits a subject (typically the output of removeBackground + alphaTrim) into a centered container on a background canvas, with an optional shadow pass.

• generateShadowLayers — the low-level shadow/vignette layer generator composeProductPhoto calls internally when shadow is set; exported for callers who want the raw layers instead of a finished composite.

Optional peer dependency

removeBackground dynamic-imports @imgly/background-removal-node, an ONNX-based ML model (~80MB download on first use), so consumers who never call it never pay that cost. Install it only if you use removeBackground:

pnpm add @imgly/background-removal-node

interface OptionalPeerMissingError extends Error {
  code: 'ERR_OPTIONAL_PEER_MISSING';
}

See Security & Heavy Dependencies for what the ~80MB model download means for constrained or cold-start environments, and Installation for the general optional-peer pattern this package uses.

Options

composeProductPhoto

ComposeProductPhotoResult: { buffer, width, height, format: 'jpeg' }.

alphaTrim

Shadow modes

GenerateShadowLayersOptions.mode picks between two lighting setups, both using a fixed upper-left light direction. Each layer group accepts a Partial<...> override of its own tuning shape (ShadowTuning, BottomShadowTuning, ProjectedShadowTuning, VignetteTuning); the table below lists the shipped defaults.

'grounded' (default) — a vignette, two bottom-fade shadows, and a tight contact shadow, as if the subject sits flush on the surface below it.

'floating' — adds a projectedShadow (a squashed, offset drop shadow suggesting the subject hovers above the surface) on top of larger-offset bottom-fade and contact shadows.

bottomShadows in GenerateShadowLayersOptions is an array of two Partial<BottomShadowTuning> | undefined overrides, positionally merged onto the mode's two defaults above.

Example

import { removeBackground, alphaTrim, composeProductPhoto } from '@takazudo/zudo-image-tweaker/product-photo';

const cutout = await removeBackground('./product.jpg');
const trimmed = await alphaTrim(cutout);
const { buffer, width, height } = await composeProductPhoto(trimmed, {
  background: { color: '#ffffff' },
  shadow: { mode: 'grounded' },
});

console.log(`${width}x${height}, ${buffer.length} bytes`);

Caveats

• composeProductPhoto requires background. Omitting it throws immediately rather than defaulting to a blank canvas.

• generateShadowLayers expects a canvas-sized, pre-positioned subject. Its alphaImage must already be the full canvas with the subject composited at its final position — each returned ShadowLayer.offset is always { x: 0, y: 0 } because the layer itself is already sized and positioned to match. composeProductPhoto builds this full-canvas image internally before calling it.

• Layers composite back-to-front: background, then shadow/vignette layers, then the subject on top — all shadow layers blend with 'multiply'.

• Upper-left is the shipped default light direction, not a fixed, unchangeable one — there's no single "light direction" knob, but you can shift the apparent lighting by overriding vignette.lightX/lightY (moves the bright center) and the shadow layers' own offsetX/offsetY (moves where each shadow falls) together, consistently, for both 'grounded' and 'floating' modes.