LYNX Python API Reference

LYNX(model, key=None, device="auto", conf=0.25, iou=0.45, track=False, ...)

1model = LYNX(
2    "lynx-basic",               # name or path
3    key=None,                  # license key (None for free models)
4    device="auto",             # "auto" / "cuda" / "cpu" / "mps"
5    conf=0.25,                 # confidence threshold (float or dict)
6    iou=0.45,                  # NMS IoU threshold
7    track=False,               # enable persistent track IDs
8    active_learning=False,     # flag low-confidence for review
9    al_conf_threshold=0.4,
10    max_latency_ms=None,       # warn if inference exceeds budget
11    deterministic=False,
12    camera=None,               # camera preset: "realsense-d435" etc.
13    output_format="numpy",     # no-op; back-compat only
14    backend=None,
15    version="latest",
16    auto_update=True,
17    behavior=False,            # temporal behavior classifier (requires track=True)
18    behavior_window=32,
19    behavior_max_tracks=32,
20    behavior_model=None,
21)

model resolution:

• Bare name ("lynx-basic") → downloaded from golynx.ai/api/models/<name>
• Path with .lnx extension → loaded from disk
• Both undergo cert chain + decrypt verification before use

conf as dict: per-class thresholds with a default:

1conf={"person": 0.5, "car": 0.3, "default": 0.25}

camera presets: "realsense-d435", "realsense-d455", "zed-2i", "zed-x" — sets intrinsics for RGBD models.

behavior=True requires track=True; behaviors fire per track_id.

model(source, depth=None, conf=None, iou=None, max_det=300, mode=None, ...) *(__call__)*

Run detection on input. Returns Results (single) or list[Results] (batch/directory).

Returns:

• Single image → Results
• Directory or list → list[Results]
• mode="ocr" → OCRResults (separate type with .text / .text_blocks)

model.encode(source, layer="pooled")

Encoder mode — extracts feature embeddings (raw feature vectors for retrieval, clustering, downstream training). Requires the model to export encoder_<layer> outputs. Raises ValueError listing available outputs if not.

Returns:

• Single input → (D,) np.ndarray
• Batch/list → (N, D) np.ndarray
• Directory → ((N, D) np.ndarray, list[str] paths)

model.classify(source, top_k=5)

Classification mode — predicts per-class probabilities. Requires a classifier artifact (lynx_is_classifier=true metadata flag + classifier_logits or classifier_probs ONNX output). Detection-only models raise ValueError.

Returns:

• Single input → Results with .probs populated, .boxes empty.
• Batch / list / directory → list[Results].

Shape of a classification Results:

Pass the Results through top_k(k) to get a Results carrying just the K most-probable classes — see Results.top_k below.

encode() returns feature vectors; classify() returns class probabilities. They are different operations served by different ONNX outputs (encoder_* vs classifier_*).

model.track(source, conf=None, iou=None, max_det=300)

Equivalent to __call__ with persistent tracking enabled. model.tracker() returns the tracker state object.

model.stream(source, conf=None, iou=None, max_det=300)

Generator that yields Results per frame for video file or webcam input.

model.export(format="onnx", output=None)

Extract the verified ONNX bytes from the loaded .lnx to disk. Only format="onnx" supported (CoreML / TFLite / TensorRT conversion happens upstream in Pax). Returns the output path.

model.benchmark(img_size=None, n=100, warmup=10)

Time n inference passes. Returns dict with timing metrics.

model.warmup(n=3)

Force-compile + run n warm-up inferences. Useful before timing-sensitive operations.

model.set_input_resolution(w, h)

Override the model's native input resolution. Subsequent calls use the new size.

Artifact-metadata accessors (v2 schema)

Every .lnx artifact built by Pax v2+ carries preprocessing convention and decoding-default metadata directly. The SDK reads it at load and exposes the resolved view through read-only properties. Use these when you need to know what the model expects without reading the producer's documentation.

The SDK preprocess path reads these automatically — customers don't need to touch them unless they want to introspect. If model.channel_order == "bgr" and you hand in cv2-loaded BGR bytes, the SDK swaps for you. If model.resize_mode == "letterbox", the SDK pre-letterboxes with model.letterbox_pad_value and back-maps predictions to source coords accounting for pad offsets.

model.metadata is a single dict carrying every v2 field plus the v1 fields (class_names, img_size, strides, output_map) and producer provenance (model_slug, model_version, producer, producer_version, training_dataset, export_timestamp). Useful for support tickets and "which model do I have loaded?" debugging.

Confidence threshold resolution. When you don't pass conf= to LYNX(), the SDK uses the artifact's lynx_default_conf_threshold. When the artifact also declares lynx_per_class_conf, the SDK promotes model.conf to a {class_name: float} dict carrying the artifact's per-class overrides plus your scalar as the "default" fallback. Passing your own conf={"car": 0.6, "default": 0.4} merges on top — your keys win, the artifact's keys survive where you didn't override.