Aperture API

Getting started

Five minutes, nothing to install, no account. By the end you will have reconstructed a hologram and know how to read every file you got back.

Step 1 — Get a hologram

Use your own, or download our sample: https://api.apertureapi.com/static/samples/inline-sample-512.png (512 × 512, 16-bit PNG, an in-line hologram of four small phase objects).

The sample was recorded with these settings — use them exactly for the sample:

Setting Value for the sample
Wavelength 0.635 µm (red laser)
Pixel pitch 1.85 µm
Hologram type inline
Focus search range 0.5 to 3.0 mm (true focus is 1.5 mm)

Done when: the PNG is saved on your computer.

Step 2 — Find your own parameters (skip for the sample)

Field Where to find it Units / common mistake
wavelength_um Your laser's label or datasheet (e.g. 405, 520, 532, 635 nm) micrometres: 635 nm is 0.635, never 635
pixel_pitch_um Your camera sensor's datasheet ("pixel size") micrometres, e.g. 1.55, 2.2, 3.45
holography_mode inline if the laser, sample and sensor sit on one straight axis with no separate reference beam; off-axis if a tilted reference beam makes straight parallel fringes; auto if unsure default is off-axis — set inline for in-line setups
z_min_mm, z_max_mm Bracket the sample-to-sensor distance; autofocus searches this range millimetres; a range of a few mm around your measured distance is fine

Step 3 — Reconstruct

Browser: open https://api.apertureapi.com/, wait three seconds, choose the file, enter the settings above, and submit. A ZIP downloads in 10–40 seconds.

Command line (same thing, two calls):

TOKEN=$(curl -sS https://api.apertureapi.com/public/form_token \
  | grep -o '"token":"[^"]*"' | cut -d'"' -f4)
sleep 3
curl -sS -X POST https://api.apertureapi.com/public/reconstruct \
  -F "file=@inline-sample-512.png" -F "form_token=$TOKEN" \
  -F "holography_mode=inline" -F "wavelength_um=0.635" \
  -F "pixel_pitch_um=1.85" -F "z_min_mm=0.5" -F "z_max_mm=3.0" \
  -o reconstruction.zip

Done when: reconstruction.zip is on disk and unzip -l reconstruction.zip lists eleven files.

Python (the same two calls with requests; downloads the sample too):

import io, time, zipfile, requests

API = "https://api.apertureapi.com"
sample = requests.get(f"{API}/static/samples/inline-sample-512.png", timeout=60)
sample.raise_for_status()
token = requests.get(f"{API}/public/form_token", timeout=30).json()["token"]
time.sleep(3)  # the form token is only accepted after a short wait
r = requests.post(
    f"{API}/public/reconstruct",
    files={"file": ("inline-sample-512.png", sample.content, "image/png")},
    data={"form_token": token, "holography_mode": "inline",
          "wavelength_um": 0.635, "pixel_pitch_um": 1.85,
          "z_min_mm": 0.5, "z_max_mm": 3.0},
    timeout=300,
)
r.raise_for_status()
open("reconstruction.zip", "wb").write(r.content)
print(len(zipfile.ZipFile(io.BytesIO(r.content)).namelist()), "files")

Done when: it prints 11 files and reconstruction.zip is on disk.

Step 4 — Read the result

  1. Open comprehensive_analysis.png — the overview figure.
  2. Open pdhm_metadata.json — reconstruction_distance_mm is where autofocus landed (about 1.53 for the sample on the current build; it was made at 1.5).
  3. Load the numbers in Python:
import zipfile, io, numpy as np
z = zipfile.ZipFile("reconstruction.zip")
d = np.load(io.BytesIO(z.read("reconstruction_data.npz")))
print(d.files)   # array names: amplitude, phase, optical_path_length_um ...
  1. Open quality_report.json. Each metric gets a band — pass, warn or fail — against a published ceiling, and overall is the worst band. A fail is a measured statement about the image (for example, residual twin-image texture in an in-line hologram), not an error in the request. We report it rather than hide it.
  2. provenance.json and evidence.json record exactly which input, settings and software produced the result.

Step 5 — Next