docs/USAGE.en.md

# Using the conversions

[Français](USAGE.md) · [English](USAGE.en.md)

## Application update — 23 September 2026

Vision Dataset Studio rc5 uses LiteRT 1.4.2 with rebuilt Flex **2.16.1-vds16k1**. Its 4/16 KB core tests are separate from the older per-model campaign and the standalone SDK; they do not qualify every conversion or the entire APK for 16 KB pages. [Runtime details](https://github.com/unicornwhodev/vision-dataset-studio/blob/65e4620/docs/FLEX_16K.md).

The original model is retained. First training creates a separate learned version, and later runs continue its latest validated weights even before inference activation. [Versions and checkpoints](CONTINUOUS_LEARNING.en.md).

## 1. Choose the exact variant

Use the [qualification matrix](BENCHMARKS.en.md). An inference graph and its `_learning` counterpart are separate artifacts. Multi-graph bundles require all graphs and processor/tokenizer files described in `pipeline.json`; do not rename one component to pretend it is a complete model. Downloaded weights are separate from the app APK.

## 2. Pin and verify

Use Python 3.11+ and `huggingface_hub`. Authenticate with `hf auth login` only if access is required; never paste credentials into source code, documentation or a command committed to Git. Select the immutable revision, then verify every manifest entry before loading:

```python
from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="fireviewer/litert-models",
    revision="330e9097409042751988e9fa5994b51ac2b577bc",
    allow_patterns=["models/fireviewer_dfine_m_strict_v1_learning/*"],
    local_dir="model-checkout",
)
```

The following check uses the folder downloaded above.

```python
from pathlib import Path
import hashlib, json

folder = Path("model-checkout/models/fireviewer_dfine_m_strict_v1_learning")  # choose the downloaded folder
for name, expected in json.loads((folder / "artifact_manifest.json").read_text(encoding="utf-8")).items():
    path = (folder / name).resolve()
    assert path.is_relative_to(folder.resolve())
    assert path.stat().st_size == expected["bytes"]
    with path.open("rb") as stream:
        assert hashlib.file_digest(stream, "sha256").hexdigest() == expected["sha256"]
```

The manifest also includes configuration files; preserve their bytes. A different revision or weight hash requires requalification. Upstream licences, notices and usage restrictions remain independent of the application’s Apache-2.0 licence.

## 3. Apply the supplied contract

Read the variant’s `runtime_contract.json` and `android_model_config.json` when present; older/bundled variants use `config.json`, `pipeline.json` and their conversion report. Respect tensor dtype/layout, RGB/BGR order, normalization, shape bounds/stride, label order and output decoder. Do not apply one family’s preprocessing to another. Resize masks with nearest-neighbour; map detections back to the original image and retain coordinate transforms. Dynamic external image dimensions may still feed a fixed frozen backbone through graph resizing.

In Vision Dataset Studio, open **Models**, configure the authorized HF source, download/import the chosen variant and contract, then inspect and run one image before batch preannotation. Manual annotation/export work without a model. Adapters existing in code do not establish compatibility for untested variants.

## 4. Runtime and learning

The converter/standalone SDK uses `org.tensorflow:tensorflow-lite:2.16.1` and `org.tensorflow:tensorflow-lite-select-tf-ops:2.16.1`. The app campaign separately used LiteRT 1.4.2 + Select TF Ops 2.16.1. These are distinct tested environments, not interchangeable guarantees. CPU, XNNPACK disabled for the learning graph, Flex/Select TF Ops for checkpoint save/restore. GPU/NPU and physical ARM remain unqualified here.

Learning requires the actual `train`, `infer`, `save`, `restore` signatures and the exact input/output names from the contract. Targets follow its `targetEncoding`, shape and labels; a missing annotation is not a negative example. Text training inputs are not supported by the current app. Heads/adapters are mutable; all supplied visual backbones remain frozen. Detection adapters cannot create proposals missing from the frozen detector. Changing the class count requires rebuilding the head.

## 5. Batch lifecycle in the app

Import → preannotate when enabled → manually correct/review → export and verify readback → optional learning on that exported batch → confirm cleanup → next batch. Learning is off by default and runs on Android. It uses accepted examples from this batch only; rejected/other-batch examples are excluded. Cleanup waits for learning and evaluation to finish; interruption/failure retains the data. Candidate weights require manual activation.

Checkpoints preserve parameters, optimizer momentum and step; keep compatible model/label hashes, dataset provenance and replay/held-out examples separately. Restored state does not prove generalization. The app requires at least 32 training and 8 validation images after its deterministic split. Persistent project fingerprints survive cleanup and reject exact file/pixel copies, but not arbitrary edited near-duplicates.

## 6. Reproduce Android integration checks

Use the [application QA tools](https://github.com/unicornwhodev/vision-dataset-studio/tree/65e4620/tools/qa) on a dedicated device with verified app and test APKs. `fetch_model_fixtures.py` downloads pinned fixtures outside the APK and verifies manifests. `qualify_converted_models.py` executes one conversion at a time and records its build, hashes and raw Android verdict. Use `--help` to supply explicit model/evidence paths and device serial. The consent variable is `VDS_ALLOW_TEST_INSTALL=1`; these scripts are QA tools, not automatic training on a user corpus. Keep failed and timed-out cases. No host optimizer is used in this app test path.

## Troubleshooting

- Hash mismatch: stop; verify revision and re-download the affected file.
- Missing Flex/Save/Restore op: check the exact CPU runtime pair and signatures.
- Tensor/stride mismatch: inspect the conversion’s shapes and decoder; the inference-only RTMDet app defect was fixed and its 22 September retest passed.
- Nonfinite loss or incompatible checkpoint: retain data and restore a previously verified compatible generation.
- Slow software emulator: functional evidence only; do not infer phone speed.

See [results and limitations](BENCHMARKS.en.md) before deploying a conversion.

[FireViewer Kotlin SDK / SDK Kotlin FireViewer](../android/README.md) includes detector target construction and DINOv3 four-task supervision. Its standalone test is separate from application integration.