# TileMosaic: file and automation reference

This technical reference describes actual local interfaces. It is not a claim of a hosted API, vendor connector or additional paid calculation. The free tool and the fixed-version kit use the same engine.

## Inputs

- layout.json + every referenced PNG basename
- input.json alone

| File | Format | Sample columns |
|---|---|---|
| `layout.json` | JSON |  |
| `r0-c0.png` | PNG |  |
| `r0-c1.png` | PNG |  |
| `r1-c0.png` | PNG |  |
| `r1-c1.png` | PNG |  |

The actual files in `samples/file-input/` are synthetic fixtures. Optional file schemas and every semantic constraint are in the [engine README](README.md). Exact JSON structure is in the product schema and README. A filename is an exact basename, never a disk path passed to the engine API.

## CLI and Python

Run from an extracted trusted kit directory using Python 3.12 or newer. TileMosaic also requires the versions in `requirements.txt`.

```sh
python3 product.py samples/valid.json output-001
```

```python
import json
from pathlib import Path
import product
payload = json.loads(Path("samples/valid.json").read_text())
report = product.run(payload)
if report["status"] != "FAIL":
    Path("result-api.zip").write_bytes(product.bundle(payload))
print(report["status"])
```

For real files, use the common `run_files.py` example: it encodes PNG/STDF bytes with base64, passes text as UTF-8, and calls `files_to_payload` before the same `run`/`bundle` functions. These are local Python functions, not HTTP endpoints. Call `run_json(text)` for strict JSON parsing; duplicate keys and nonfinite numbers are refused.

## Batch folders and exact column profile

Each immediate subdirectory of `jobs/` is one independent engine payload. Copy all required files into that folder. Use `input.json` for a multi-period RoyaltyWaterfall history or an explicitly ordered multi-file TestLotReplay history; splitting those dependent histories into independent folders does not carry state.

```sh
mkdir -p jobs/example
cp samples/file-input/* jobs/example/
python3 batch.py jobs results-001
```

A profile maps destination header to source header. This complete example corresponds to the sample CSV files with every header renamed to `export_...`; normal sample headers need no profile.

```json
{}
```

Save the profile as `columns.json` outside the job folder, then run `python3 batch.py jobs results-002 --profile columns.json`. For PNG/STDF/JSON-only inputs the profile is `{}` and can be omitted. Profiles rename columns only: no unit, currency, timestamp or value conversion. Destination order is significant for strict CSV readers. The outer runner deliberately projects only mapped columns; retain and review the original export. Missing/duplicate headers, ragged rows and nonunique mapped source columns fail. Engine-specific validation still runs after mapping.

## Result file schema observed by executable example

Columns and JSON keys observed in the synthetic PASS fixture; variable recipient, source, pyramid and map filenames depend on input. Read README.md for UNKNOWN omissions and semantic rules.

| ZIP member | CSV columns or observed JSON keys |
|---|---|
| `README.txt` |  |
| `alignment-residuals.csv` | `accepted`, `candidates_tested`, `dx`, `dy`, `expected_dx`, `expected_dy`, `from_col`, `from_row`, `kind`, `margin`, `ncc`, `overlap_pixels`, `phase_peak`, `reason`, `residual_dx`, `residual_dy`, `runner_up_ncc`, `to_col`, `to_row` |
| `calibration.json` | `canvas_origin_anchor_x_px`, `canvas_origin_anchor_y_px`, `height_um`, `pixel_scale_um`, `scope`, `status`, `width_um` |
| `coverage-count.png` |  |
| `coverage-mask.png` |  |
| `input.json` | `grid`, `intensity_mode`, `note`, `overlap`, `pixel_scale_um`, `schema`, `tiles` |
| `manifest.json` | `product`, `sha256`, `status`, `version` |
| `mosaic.png` |  |
| `pyramid.json` | `bits`, `downsample`, `levels`, `mode`, `tile_size` |
| `pyramid/level-0/0-0.png` |  |
| `pyramid/level-1/0-0.png` |  |
| `pyramid/level-2/0-0.png` |  |
| `pyramid/level-3/0-0.png` |  |
| `pyramid/level-4/0-0.png` |  |
| `pyramid/level-5/0-0.png` |  |
| `pyramid/level-6/0-0.png` |  |
| `report.json` | `findings`, `provenance`, `status`, `summary`, `tables` |
| `source-manifest.json` | `scope`, `tiles` |
| `sources/r0-c0.png` |  |
| `sources/r0-c1.png` |  |
| `sources/r1-c0.png` |  |
| `sources/r1-c1.png` |  |
| `transforms.csv` | `anchor_x_px`, `anchor_y_px`, `col`, `height_px`, `label`, `row`, `width_px`, `x_px`, `y_px` |

CSV text that could execute as a spreadsheet formula is neutralized; original JSON preserves exact text. Read report status and the relevant coverage/completeness fields before importing numeric rows. UNKNOWN is an unobserved result, not zero. PASS is computation under declared inputs and policies, not a professional conclusion.

## Supported handoffs

- **Buyer-owned exported tile grid → TileMosaic** (PNG + JSON): Export the supported grayscale/RGB PNGs upstream and declare rows, columns, overlap and optional scale in layout.json. Supported local file boundary only; upstream export and downstream product compatibility require buyer validation.
- **mosaic.png + coverage-mask.png + calibration.json → Buyer-owned image analysis** (PNG + JSON): Read image and coverage together; apply only the supplied scale. Image opening is a file handoff, not an ImageJ or microscope connector. Supported local file boundary only; upstream export and downstream product compatibility require buyer validation.

## Scope boundaries

- Up to 64 same-size PNG tiles; integer translation at fixed magnification; L or RGB input becomes 8-bit grayscale.
- No TIFF, OME-TIFF, rotation, subpixel registration, z-stacks or microscope control.
- Ambiguous alignment yields UNKNOWN and no final mosaic. Scale is buyer-declared; original color and PNG metadata are not retained.
- The custom PNG pyramid is documented output, not a standard viewer protocol. Browser and batch bounds can be lower than engine bounds.

## Replay evidence

Engine SHA256: `2709d6aa00864939ddf5c6c5870a9498c6cf99fa00d830ed2e8eced9ef4cc305`.

The documentation builder ran the actual synthetic file set and reopened its result archive. This verifies the local format example, not customer file compatibility, deployment, demand or financial return. Same-version bytes can be compared in one pinned environment; Python/zlib or TileMosaic dependency upgrades can change archive bytes.

See the [common automation reference](../integrations.md) for scheduling, CI and batch receipt semantics.