---

name: export description: "Export, profile, and prepare NanoTrack split backbone/head models for ONNX and deployment handoff with explicit shape, artifact, and benchmark safeguards." disable-model-invocation: true metadata: disco-role: operating license: NO_LICENSE

NanoTrack Export and Deployment Handoff

Use This Sub-skill When

Use this sub-skill for NanoTrack requests involving:

• split backbone/head ONNX export;
• ONNX input, output, name, or opset inspection;
• optional ONNX simplification planning;
• MAC, parameter, model-size, or throughput measurement;
• a bounded handoff to NCNN or a mobile inference implementer.

This guidance covers the maintained NanoTrack workflow. Treat other SiamTrackers snapshots as catalog entries unless another sub-skill explicitly owns them.

Route Elsewhere

• Route frame preprocessing, template caching, search updates, and result decoding to the inference sub-skill.
• Route optimization, loss, data loading, and checkpoints produced by learning to the training sub-skill.
• Route dataset metrics and benchmark protocols to the evaluation sub-skill.
• Android, iOS, macOS, C++, NCNN builds, and third-party conversion services are documentation-only boundaries here; this sub-skill does not claim those toolchains work.

Start From the Verified Contract

The source export intent is a two-graph NanoTrackV3 contract:

Graph	Inputs	Outputs	Opset
backbone	input: [1,3,255,255]	output: [1,96,16,16]	14
head	input1: [1,96,8,8]; input2: [1,96,16,16]	output1: [1,2,15,15]; output2: [1,4,15,15]	14

output1 is the classification tensor and output2 is the positive localization tensor returned by the NanoTrackV3 head. Read export-reference.md before changing graph boundaries, spatial axes, head variant, or preprocessing assumptions.

This is an evidence-backed intended contract, not a claim that an export was successfully run or validated. A compatible configuration and trusted weights are required. No weights are bundled with this skill.

Choose a Workflow

Validate a proposed split contract

Run the no-write checker from this sub-skill directory:

python scripts/export_shape_check.py

To inspect already-created ONNX graphs, install onnx in the caller-controlled environment and pass both files:

python scripts/export_shape_check.py \
  --backbone-model artifacts/backbone.onnx \
  --head-model artifacts/head.onnx

The paths above are placeholders for caller-owned artifacts. The checker never downloads, exports, creates directories, or overwrites files.

Plan output artifacts safely

Use a caller-owned staging directory and relative names. Names are examples, not required filenames:

python scripts/export_shape_check.py \
  --artifact-root artifacts \
  --backbone-name release/backbone-v3.onnx \
  --head-name release/head-v3.onnx

The checker rejects absolute artifact names, .. traversal, duplicate targets, non-ONNX suffixes, and existing targets unless explicitly acknowledged. Read export-reference.md for export, validation, simplification, and manifest gates.

Plan profiling or throughput work

Validate a benchmark plan without importing PyTorch or running long loops:

python scripts/profile_shape_check.py \
  --device cpu --timer wall --warmup 100 --iterations 1000 --repeats 5

For wall-clock CUDA timing, require synchronization around each timed region:

python scripts/profile_shape_check.py \
  --device cuda --timer wall --synchronize \
  --warmup 100 --iterations 1000 --repeats 5

Read performance.md before interpreting MACs as FLOPs, comparing model file sizes, or reporting FPS.

Safe Export Gates

1. Variant gate: confirm the backbone, adjust channels, head implementation, and checkpoint all belong to the same NanoTrack version.
2. Weight gate: load a trusted checkpoint with key/shape diagnostics; do not silently profile or export random initialization.
3. Mode gate: use one model instance in evaluation mode and disable gradient recording during representative forwards.
4. Shape gate: verify template image 127x127, search image 255x255, backbone features 96x8x8 and 96x16x16, and head outputs 2x15x15 and 4x15x15 for NanoTrackV3.
5. Artifact gate: write to a new caller-owned staging path, never a hard-coded repository-relative destination and never over an existing artifact by default.
6. ONNX gate: check graph syntax, opset, names, dtypes, and static/dynamic dimensions, then compare outputs in a separate runtime when available.
7. Simplification gate: preserve the unsimplified graph, write simplification to a distinct name, check the simplifier result flag, and rerun parity.
8. Deployment gate: record hashes and preprocessing/postprocessing contracts; conversion alone does not prove mobile correctness or speed.

Important Static-Shape Warning

A backbone exported only from [1,3,255,255] without dynamic axes is normally a static search graph. The head nevertheless needs a template feature of [1,96,8,8], which comes from the 127x127 template path in PyTorch. Do not assume one static 255x255 ONNX backbone also accepts 127x127. Choose and validate one explicit design: dynamic spatial axes, separate template/search backbone artifacts, or a deployment pipeline with an independently justified template-feature path.

Dependency and Backend Policy

• torch is needed to instantiate and export the model.
• onnx is optional but required for structural graph checking.
• onnxruntime is optional and useful for numerical parity.
• onnxsim is optional; simplification is not an automatic success gate.
• thop is optional and provides MAC/parameter estimates, not universal FLOP semantics.
• Historical environment pins are compatibility clues, not install commands. Resolve versions against the current Python, PyTorch, ONNX, and target-runtime compatibility matrices instead of copying obsolete pins.
• Prefer CPU export for portability when supported. If CUDA is selected, record device/backend details and synchronize timing; CUDA availability alone does not prove ONNX or mobile backend support.

Known Limits

No dataset benchmark, full tracker run, training run, ONNX export, numerical parity run, NCNN conversion, or mobile build is proven by this sub-skill. The source export workflow used snapshots, hard-coded output paths, and automatic CUDA selection. Its speed loop warmed up 100 times and timed 1000 track calls; that is methodology evidence, not a safe construction-time smoke test.

Use troubleshooting.md for missing weights, variant mismatches, shape errors, optional dependencies, CUDA timing, ONNX simplification, and deployment-boundary failures.