<!-- examples/README-sam.md -->

# Original SAM inference reference

Put `sam.py`, `sam_export.py`, and the extracted `sam_native/` directory beside one another. Install `requirements-sam.txt` in your own environment. CPU Torch wheels are sufficient.

```sh
unzip sam_native.zip
python sam.py --smoke
```

The offline profile constructs reduced random-weight native modules: 64-square images, 16-square patch size, two width-64 ViT blocks, 32-channel image/prompt embeddings, and a two-block decoder. It tests geometry, prompts, decoding, and reuse without a checkpoint, network, or ignored research cache. It does not demonstrate pretrained semantics or reproduce SAM training. The encoder is frozen as an inference/reuse choice, not a statement about original training.

## Authenticate the source

The native archive contains unchanged official modeling/build modules plus the original Apache-2.0 LICENSE. Every native file is verified against its complete SHA256 in `sam_native/source-manifest.json` before import. Original copyright headers are retained. The only compatibility adapter creates a package namespace to bypass the optional automatic-mask-generator imports. No native classes are changed.

Official source revision: `dca509fe793f601edb92606367a655c15ac00fdf`.

Archive SHA256: `6ad5ea1ba9d117f4799d6d2c2c506550a3a6700e87776900f45429ddc11c0844`.

For independent source retrieval, the manifest lists exact raw GitHub URLs and hashes. Retrieve each manifest file into `sam_native/<manifest path>` and verify its full SHA256. URLs have this form:

`https://raw.githubusercontent.com/facebookresearch/segment-anything/dca509fe793f601edb92606367a655c15ac00fdf/<manifest path>`

Source files are unchanged archived bytes; the authored wrappers live outside that source tree. Both local tests and the public download verify the same native sources.

## Reproduce genuine real-photo inference

Download the official ViT-B checkpoint:

`https://dl.fbaipublicfiles.com/segment_anything/sam_vit_b_01ec64.pth`

Full SHA256: `ec2df62732614e57411cdcf32a23ffdf28910380d03139ee0f4fcbe91eb8c912`.

```sh
python sam_export.py --checkpoint sam_vit_b_01ec64.pth --output sam-demo
```

The exporter fetches and verifies two CC0 photographs from the pinned scikit-image v0.25.2 release. To avoid photo downloads, supply `--photo-dir` with `source-cat.png` and `source-coffee.png` from the example artifacts. Image authors and exact source/license URLs are recorded in `predictions.json`. The official checkpoint stays outside Git and is authenticated before loading with `weights_only=True` and `strict=True`. This is original SAM ViT-B/16, not SAM 2, ViT-H, a distilled variant, or a benchmark reproduction.

The exporter encodes each photo once, decodes one foreground point into all three native multimask alternatives, explicitly selects the highest predicted IoU for an overlay, and performs a second mask-logit refinement using the cached embedding. It compares wrapper logits, IoU predictions, and postprocessed logits against the native decoder and postprocessing. `predictions.json` records exact program/export/source/checkpoint/image hashes, runtime versions, command, seed, threads, architecture, and preprocessing. The `.npz` files retain actual logits, masks, scores, input points/labels, and refinement logits; individual binary masks are saved as PNGs. These quality scores are IoU regressions for ranking, not calibrated probabilities or measured ground-truth IoUs.

## Input and output contract

Images are converted to RGB, longest-side resized to 1024 with Pillow bilinear interpolation and official round-half-up dimensions, and represented as float32 0..255 pixels. RGB means are `[123.675,116.28,103.53]`; standard deviations are `[58.395,57.12,57.375]`. After normalization, right/bottom zero padding makes the 1024-square input. Point x/y scales use the actual rounded width/height before the native half-pixel shift. Foreground is label 1, background 0, and internal padding −1. Boxes use two distinct corner types. A refinement mask is unthresholded low-resolution logits, not a binarized image.

Output logits are bilinearly resized to the padded 1024 square, cropped to resized height/width, bilinearly resized to original dimensions, then thresholded at zero. Both interpolations use `align_corners=False`. Native multimask mode returns tokens 1..3; single mode returns token 0, rather than argmax among the three. The released native encoder supports points, boxes, and masks, without the paper's separate text experiments.
