LYNX Python API Reference

The Python import path is always import lynx, regardless of which distribution (lynx, lynx-cpu, lynx-jetson, …) you installed. Python 3.10–3.14.

Install

🧪 Beta: the beta ships from Synetic's own package index, not public PyPI (see README → Beta install): pip install lynx --extra-index-url <your beta index URL — provided at onboarding>. The plain commands below apply once the SDK reaches general availability on public PyPI.

1pip install lynx                  # default — GPU on Linux, CoreML on macOS, DirectML on Windows
2pip install lynx-cpu              # Linux opt-in lean wheel, CPU-only ONNX Runtime

Quickstart

1import lynx
2 
3lynx.set_license("YOUR_API_KEY")          # or export $LYNX_API_KEY
4 
5with lynx.open("lynx-basic") as model:    # download + open by slug
6    frame = model.predict("image.jpg")
7    for det in frame.detections:
8        name = model.classes(det.class_id).name
9        print(name, float(det.confidence), det.box.tolist())

Core model

A model is opened by slug. open() returns a Model; predict() returns a Frame; a Frame holds a Detections collection. Each piece is documented below.

Module functions

METHODopenclick to expand

open(slug="lynx-basic", *, tasks=Task(0), conf=None, size=None, goal=None, nms=Nms.AUTO, version=None) -> Model

Open one model by slug. tasks=0 opens every head the model declares; conf=None uses the model's calibrated balanced operating point.

METHODset_licenseclick to expand

set_license(key: str) -> None

Store the per-account API key (the model-download credential).

METHODversionclick to expand

version() -> str

The SDK version string. The name really covers it — we will spare you the padding.

METHODprovidersclick to expand

providers() -> list[Provider]

Execution providers available on this host.

METHODcuda_device_countclick to expand

cuda_device_count() -> int

Number of visible CUDA devices (0 if none).

METHODset_workersclick to expand

set_workers(gpus=None, cpus=None) -> None

Configure compute workers — call once at startup, before open()/predict(). gpus: sequence of CUDA ids, an int count, or None/0 (CPU). cpus: worker-thread count or None (auto).

METHODcamera_openclick to expand

camera_open(index=0, *, width=0, height=0, fps=0.0) -> Camera

Open a webcam source (0 = device default).

METHODvideo_writerclick to expand

video_writer(path, width, height, fps=30.0, *, quality=85) -> VideoWriter

Open a Motion-JPEG/AVI recorder.

METHODdepth_to_u8click to expand

depth_to_u8(frame: Frame)

Render a frame's depth as a displayable (H,W,3) uint8 RGB image (closer = brighter); None if no depth.

lynx.license() raises — licensing is per-model; use Model.license.

Model

Constructed only via open / load. Context manager (with lynx.open(...) as model:).

Properties:

Property	Type
`version`
`build_id`
`capabilities`	`Task`
`nms_free`	`bool`
`size`	`ModelSize`
`license`	`License`
`providers`	`list[Provider]`
`available_batch_sizes`	`list`

classes — a synthesized IntEnum of the model's class names (a per-model attribute, not a fixed enum). Resolve a name with model.classes(class_id).name. Pose classes carry a nested .kp keypoint enum.

METHODpredictclick to expand

predict(image, *, conf=None, max_det=0, tasks=Task(0), retain=False, nms=Nms.AUTO, ocr=None) -> Frame

Inference on one image (path or (H,W,3) uint8 RGB) — or a sequence → list[Frame]. ocr is an Ocr mode (OFF/AUTO/ON/HORIZONTAL/VERTICAL, or a bool); AUTO (default) runs OCR iff the model declares TEXT.

METHODtrackclick to expand

track(source, *, window=0.0, ocr=None)

Generator; yields a Frame per image in source with tracker ids populated. ocr is an Ocr mode.

METHODtrackerclick to expand

tracker(*, window=0.0, ocr=None) -> Tracker

Open a streaming tracker. ocr is an Ocr mode.

METHODocr_tiledclick to expand

ocr_tiled(image, *, windows=None, overlap=0.05, resize_to=640, variants=("as_is","rb_swap","invert","invert_rb"), despeckle=3, conf=0.1, max_det=0) -> dict

Tiled multi-window/variant OCR; returns a grouped document dict. image must be a decoded (H,W,3) uint8 RGB array.

METHODpose_edgesclick to expand

pose_edges(cls) -> list

Skeleton edges as (kp-name, kp-name) tuples; empty for non-pose classes.

METHODprepareclick to expand

prepare(batch_sizes) -> None

Pre-build inference engines for the given batch sizes.

METHODcloseclick to expand

close() -> None

Release the model.

Frame

The result of predict(). Iterating/indexing a Frame yields one FrameResult per detection (for r in frame: ..., frame[i], len(frame)).

Attributes / properties:

detections -> Detections

The detection collection.

classifications -> Classifications

Whole-image top-1 label (if a classification head ran).

document

Typed Document (.text, .blocks, .vertical_text, .text_all) — populated when OCR runs, else None.

depth_map

Dense HxW depth ndarray, or None.

depth_is_metric -> bool

True → depth is in meters.

METHODdepth_u8click to expand

depth_u8()

Displayable (H,W,3) uint8 RGB depth image, or None.

flow

Optical-flow output, if present.

tracks -> list[Track]

Active tracks for this frame.

METHODindex_ofclick to expand

index_of(track_id) -> int

Row index of a track id.

METHODobject_distanceclick to expand

object_distance(a, b) -> float

Distance between two detections; nan if unavailable.

METHODrunclick to expand

run(tasks, *, where=None) -> None

Realize a deferred frame-global head (e.g. Task.DEPTH) against retained features.

METHODplotclick to expand

plot(*, watermark=True, image=None, **opts)

Annotated RGB image. image= (the decoded source) is required.

METHODsubmit_feedbackclick to expand

submit_feedback(image, correction) -> None

Send a correction (telemetry); re-supply the source image.

Detections & Detection

Detections is the vectorized collection on frame.detections. len(), iteration (→ Detection), and __getitem__ (int → Detection; slice / bool array / int array → a sub-collection view) are supported.

Detections columns (NumPy arrays):

Column	Notes
`boxes`
`oriented_boxes`
`class_id`
`confidence`
`tracker_id`
`track_state`
`track_age`
`masks`	list
`embeddings`
`text`	list
`keypoints`	lazy object with `.xy` `(N,K,2)` and `.conf` `(N,K)`

Detections methods:

METHODangle_atclick to expand

angle_at(kp)

(N,) float32

METHODdistanceclick to expand

distance(a, b)

(N,) float32

METHODdistance_toclick to expand

distance_to(point)

(N,) float32

METHODrunclick to expand

run(tasks, *, where=None)

Detection — a scalar view of one detection:

box, oriented_box

Bounding box row(s).

class_id -> int, confidence -> float

Class + score.

keypoints, mask, embedding, text

Per-head outputs (when present).

depth -> float

Meters (metric models) / relative; nan if no depth.

metric_size -> float

Implied √(h·w) in meters; nan if scale unresolvable.

size_plausibility -> float

[0,1] fit to the class size band (1 = in-band / not judged).

size_verdict -> SizeVerdict

OK / TOO_SMALL / TOO_LARGE / NO_BAND / NO_SCALE.

adjusted_score -> float

confidence × size_plausibility.

METHODposition_3dclick to expand

position_3d(intrinsics: Intrinsics) -> Point3D \

None` — Camera-frame 3D point (needs depth).

METHODbox_3dclick to expand

box_3d(intrinsics: Intrinsics) -> Box3D \

None` — Camera-frame 3D box.

tracker_id -> int, track_state -> TrackState, track_age -> float, track

Tracking fields (when tracking).

METHODangle_atclick to expand

angle_at(kp) -> float, distance(a, b) -> float

Pose geometry.

behavior / respiration / pulse are reserved (temporal heads) and currently return None.

Tracking

1with lynx.open("lynx-basic") as model:
2    for frame in model.track(frames, window=2.0):
3        for det in frame.detections:
4            print(det.tracker_id, det.track_state.name, det.track_age)

Streaming Tracker (from model.tracker(...), a context manager):

METHODupdateclick to expand

update(image, *, ocr=None) -> Frame

Process one frame synchronously; tracker ids populated.

METHODsubmitclick to expand

submit(image) -> int

Enqueue a frame for async processing (non-blocking).

METHODprocess_nextclick to expand

process_next(*, ocr=None) -> Frame

Dequeue + infer the next enqueued frame (blocks). Pairs with submit.

METHODvalueclick to expand

value(track_id, kp, *, attr: Attr, op: Op, window: float, unit: Unit) -> float

Temporal measurement over a track; nan if unavailable.

METHODcloseclick to expand

close() -> None

Stop the tracker.

Read tracks from the Frame returned by update() (frame.tracks) — Tracker.tracks raises by design.

Track value object:

Field	Type
`id`	`int`
`state`	`TrackState`
`age_s`	`float`
`box`	float32 ndarray
`matched`	`bool`

OCR

1# on a loaded OCR model:
2frame = model.predict(rgb_array, ocr=Ocr.AUTO)   # or ocr=True; Ocr.OFF/ON/HORIZONTAL/VERTICAL
3doc = frame.document                              # a typed Document (None if OCR didn't run)
4print(doc.text)                                   # horizontal reading
5for v in doc.vertical_text:                       # vertical columns (e.g. a top-to-bottom ID)
6    print(v.text)
7for block in doc.blocks:
8    for line in block.lines:
9        print(line.text, [w.char for w in line.words])

OCR inputs must be decoded (H,W,3) uint8 RGB arrays.

Depth & 3D

1frame  = model.predict("scene.jpg", tasks=lynx.Task.BOX | lynx.Task.DEPTH)
2dmap   = frame.depth_map           # HxW ndarray or None
3metric = frame.depth_is_metric     # bool
4vis    = lynx.depth_to_u8(frame)   # (H,W,3) uint8 RGB
5 
6# 3D back-projection (needs pinhole intrinsics, in pixels):
7intr = lynx.Intrinsics(fx=900.0, fy=900.0, cx=640.0, cy=360.0)
8for det in frame.detections:
9    p = det.position_3d(intr)      # Point3D(x, y, z) or None
10    b = det.box_3d(intr)           # Box3D(center, width, height) or None

Confidence & tasks

open()/predict() default to every declared head at the model's calibrated balanced operating point. Override per call:

1model.predict(img, conf=lynx.ConfMode.MAX_PRECISION)   # MAX_RECALL / BALANCED / MAX_PRECISION
2model.predict(img, conf=0.5)                            # raw float threshold
3model.predict(img, tasks=lynx.Task.BOX | lynx.Task.SEGMENTATION, max_det=100)

conf= accepts:

Accepted value	Notes
`None`	open-time default
a `ConfMode`
a `Conf` selector	`Conf.balanced()`, `Conf.max_recall()`, `Conf.max_precision()`, `Conf.value(t)`
a bare float

Enums

Task (IntFlag) members:

BOX

1

OBB

2

SEGMENTATION

4

DEPTH

8

POSE

16

CLASSIFICATION

32

REID

64

TEXT

128

METHODTaskclick to expand

Task(0)

all declared heads

Other enums:

Enum	Members
`ConfMode`	`BALANCED`, `MAX_RECALL`, `MAX_PRECISION`
`Nms`	`AUTO`, `ON`, `OFF`
`Provider`	`CPU`, `CUDA`, `TENSORRT`, `COREML`
`TrackState`	`NEW`, `TENTATIVE`, `CONFIRMED`, `LOST`
`SizeVerdict`	`OK`, `TOO_SMALL`, `TOO_LARGE`, `NO_BAND`, `NO_SCALE`
`Size`	`AUTO`, `PICO`, `NANO`, `MEDIUM`, `LARGE`
`Goal`	`BALANCED`, `LATENCY`, `THROUGHPUT`
`LicenseStatus`	`VALID`, `EXPIRED`, `UNKNOWN`
`Attr`	`LOCATION_X`, `LOCATION_Y`, `ANGLE`, `SPEED`, `CONFIDENCE` (for `Tracker.value`)
`Op`	`LATEST`, `DELTA`, `RATE`, `MEAN`, `MIN`, `MAX` (for `Tracker.value`)
`Unit`	`FRAMES`, `SECONDS` (for `Tracker.value`)

Value types:

Type	Fields
`License`	`status`, `expires_at`, `is_perpetual`, `is_paid`
`ModelSize`	`category: Size`, `num_params`, `disk_bytes`
`Intrinsics`	`fx,fy,cx,cy`
`Point3D`	`x,y,z`
`Box3D`	`center,width,height`

Camera & video I/O

1cam = lynx.camera_open(0)                       # webcam
2writer = lynx.video_writer("out.avi", 1280, 720, fps=30.0)
3with cam, writer:
4    for _ in range(300):
5        rgb = cam.read()                        # (H,W,3) uint8 RGB
6        frame = model.predict(rgb)
7        writer.write(frame.plot(image=rgb))
8    writer.finish()

Camera:

METHODreadclick to expand

read()

actual_format

property → (w,h,fps)

METHODcloseclick to expand

close()

VideoWriter:

METHODwriteclick to expand

write(frame)

frames

property

METHODfinishclick to expand

finish()

METHODcloseclick to expand

close()

CLI

1lynx info <slug>             # version, capabilities, classes, license, providers
2lynx predict <slug> <image>  # run one image, print detections (alias: lynx detect)
3lynx providers               # execution providers on this host
4lynx --version               # SDK version

I/O flags:

Flag	Value
`--model` / positional	slug
`--source` / `--input` / positional	image
`--license`	else `$LYNX_API_KEY`