Basic Object Detection

from fotonet import Fotonet
import cv2

# Load model checkpoint
model = Fotonet("fotonete")

# Read image and run inference (conf=0.25)
frame = cv2.imread("sample.jpg")
results = model.predict_bgr(frame, imgsz=640, conf=0.25)

# Print detected bounding boxes and scores
for box in results[0].boxes:
    print(f"Class: {box.cls} | Score: {box.conf:.3f} | BBox: {box.xyxy}")

Related Sections

Official Checkpoint Lineup

Every published weight uses the same fixed graph (1,723,672 training parameters; 1,698,564 deployment parameters):

Checkpoints are written continuously during training, so the fingerprint above refers to the snapshot used for the currently published benchmark figures. Weights are distributed through GitHub Releases and never committed to the repository.

Strict Mathematical Contract

fotonet ships exactly one accepted graph. Every proposed code refactor must guarantee:

• Output tensor shape strictly preserved: [Batch, 8400, nc + 4] (where nc = 80, 4 = xywh coordinates).
• Exact integer channel counts across stages: Backbone [64, 96, 160], Neck [64, 96, 160].
• No conversion scripts required when resuming training or loading public weights.
• Unvarying architecture_fingerprint hash across all platforms.

Design Principles

Traditional transformer and depthwise architectures incur significant latency overhead on edge memory busses. fotonete utilizes dense residual blocks operating with explicit integer channels, keeping compute density high while maintaining a small GPU footprint.

One-to-One vs One-to-Many Dual Training

During training, two branches operate simultaneously:

• Auxiliary One-to-Many Branch: Provides rich gradient supervision during early epochs for rapid convergence.
• Deploy One-to-One Branch: Matches exactly 1 prediction per ground-truth bounding box via Hungarian bipartite matching.

At deployment time, the auxiliary branch is completely discarded with zero cost. Predictions from the one-to-one head are 100% deterministic and require no NMS heuristics.

Fotonet(weights_path)

Initializes the deploy graph and auto-detects CUDA / CPU availability.

Methods:

• model.predict_bgr(image_or_path, imgsz=640, conf=0.25): Primary entrypoint for OpenCV BGR images or file paths.
• FastPredictor(model, device="cuda", half=True): High-throughput path with pinned memory and a reusable staging buffer; predict(frame) returns an (N, 6) array of x1, y1, x2, y2, score, class.
• model.export(format="onnx", **kwargs): Export engine supporting ONNX, TensorRT, and CoreML.

Pinned Memory & CUDA Stream Binding

By pinning host memory and reusing one staging buffer and one GPU tensor per stream, per-frame allocation and host-device roundtrips disappear, bringing end-to-end latency down toward the pure GPU-pass time (see the Benchmarks section for current measured figures).

What the measured pipeline covers

The figures below are TensorRT stage timings, not PyTorch and not browser ONNX timings. Each engine was measured in a fresh trtexec process with a 1-second warmup, a 10-second timed window, and 10-run averages. TensorRT reports GPU compute, host latency, enqueue, H2D, and D2H separately; these stages can overlap and must not be added together. For this like-for-like comparison, the Fotonete benchmark wrapper applies the existing two-stage top-300 selector and emits [B,300,6] rows in x1,y1,x2,y2,score,class_id order. The underlying Fotonete checkpoint, architecture, and raw production output contract remain unchanged. YOLO26n is an end-to-end checkpoint and its TensorRT output is explicitly verified as [B,300,6]; Ultralytics ignores the generic NMS flag for this end-to-end model because the 300-row output is already part of the graph.

Fotonete final-row TensorRT stage speeds

Measured on the RTX 4060 with TensorRT 10.16.1. Values below are the median and 90th-percentile latency reported by trtexec for the timed window.

The timed engine used random input bindings and measured TensorRT execution only. The Fotonete selector is included in the benchmark engine; image decoding and preprocessing are not.

Fotonete vs YOLO26n

Both systems were compiled as static FP16 TensorRT engines at 640 x 640 and measured on the same RTX 4060 using the same trtexec protocol. YOLO26n was exported with max_det=300; both ONNX outputs were shape-checked as [B,300,6]. The comparison is runtime-only and does not change or imply an accuracy claim.

1-Line CLI Export

fotonet export model=fotonete.pt format=onnx path=fotonete.onnx opset=17

Cost Matching Equation

The bipartite matching cost between prediction $i$ and ground truth $j$ is formulated as:

Cost(i, j) = λ_cls · FL(p_i, c_j) + λ_box · L1(b_i, b_j) + λ_siou · SIoU(b_i, b_j)

Automatic Resume

fotonet train model=fotonete data=my_dataset.yaml resume=fotonet_last.pt

Test Bench Specifications

• CPU: 13th Gen Intel Core i3-13100F · 4 cores / 8 threads
• GPU: NVIDIA GeForce RTX 4060 (8 GB VRAM) · driver 610.74
• Memory: 2133 MHz configured memory speed
• Storage: WDC WDS480G2G0C SSD · 2,229 MB/s measured sequential read
• Runtime: Windows 11 · CUDA 12.8 · PyTorch 2.11.0+cu128
• Load: Benchmarks are recorded in a clean process with no training job running. PyTorch latency uses 80 end-to-end and 150 forward iterations per worker; mAP uses the full COCO val2017 validation set. TensorRT uses a separate 10-second trtexec window after a 1-second warmup. Peer models (YOLO26n and D-FINE N) are evaluated on the same machine; nothing is quoted from vendor pages.