Input contract

What a hologram upload must look like, and what happens when it does not. Each refusal has a stable code, listed on the error-meanings page.

File formats

Accepted extensions: .h5, .hdf5, .jpeg, .jpg, .npy, .npz, .png, .tif, .tiff. Anything else is refused with INPUT_FORMAT_UNSUPPORTED.

Bit depth. 8-bit and 16-bit integer frames are read at full depth; .npy / .npz / .h5 arrays are read as stored. Send the camera's native bit depth: a 16-bit frame keeps fringe contrast an 8-bit export throws away.
Monochrome sensors. Upload the frame as is (one 2-D image).
Colour sensors. An RGB or RGBA image is reduced to one intensity plane. For a Bayer-mosaic camera, the cleanest input is the green channel exported as a monochrome 16-bit PNG or TIFF without demosaicing, because demosaicing interpolates across the fringes.
One frame per file. More than three axes, or a channel count other than 1, 3 or 4, is refused with INPUT_CHANNELS_UNSUPPORTED.

Required metadata

Parameter	Unit	Allowed range
`wavelength_um`	micrometres	greater than 0.1, at most 20.0
`pixel_pitch_um`	micrometres	greater than 0.1, at most 1000.0, and strictly greater than `wavelength_um`

Wavelength is in micrometres: 0.635, not 635. A pitch that is not above the wavelength is refused with PARAM_PITCH_NOT_ABOVE_WAVELENGTH.

Optional inputs

reference_file: a frame of the same setup with no sample in it, used for background subtraction. It is checked against the same contract as the hologram.
geometry: unspecified | transmission | reflection (default unspecified). With unspecified, the surface output is optical path length; reflection adds a height. Any other value is refused with PARAM_MODE_INVALID.

Limits

Limit	Value
Image width or height	at most 4000 px per axis, read from the file header before decoding (`INPUT_DIMENSIONS_TOO_LARGE`)
Upload size	64 MB or 75 MB depending on plan (tier-limits page); 75 MB is the service ceiling (`INPUT_FILE_TOO_LARGE`)
`processing_profile=standard`	working field up to 1080 x 1920 px (rows x columns); larger frames are centre-cropped, never downscaled
`processing_profile=xhigh`	working field up to 3000 x 4000 px (rows x columns); larger frames are centre-cropped, never downscaled
Memory	if the requested field will not fit in free memory the request is refused with `CAPACITY_INSUFFICIENT_MEMORY` (507) instead of failing mid-run

Crop to the region of interest rather than downscaling: downscaling changes the effective pixel pitch and can destroy off-axis carrier fringes.

Checks, in order

Empty file: INPUT_EMPTY.
Dimensions from the header, before any decode: INPUT_DIMENSIONS_TOO_LARGE.
Channel layout: INPUT_CHANNELS_UNSUPPORTED.
Full decode; a truncated or mislabelled file is INPUT_UNREADABLE.
Every pixel the same value (all dark or fully saturated): INPUT_BLANK.
Partial saturation is recorded as a flag in the quality report, never a refusal.