Crate locus_core 

High-performance AprilTag and ArUco detection engine.

Locus is a research-oriented, memory-safe fiducial marker detector targeting low latency. It provides a performance-focused pipeline for robotics and computer vision, with strict zero-heap allocation in the detection hot-path.

Key Features

• Performance: SIMD-accelerated adaptive thresholding and connected components.
• Accuracy: Advanced sub-pixel refinement and probabilistic pose estimation.
• Flexibility: Pluggable tag families (AprilTag 36h11, 16h5, ArUco).
• Memory Safety: Arena-based memory management (bumpalo).

Architecture

The pipeline is designed around Data-Oriented Design (DOD) principles:

1. Preprocessing: threshold::ThresholdEngine computes local tile statistics and performs adaptive binarization.
2. Segmentation: segmentation::label_components_threshold_model identifies quad candidates using Union-Find.
3. Extraction: quad::extract_quads_with_config traces contours and fits initial polygon candidates.
4. Decoding: Detector samples bit grids and performs Hamming error correction via strategy::DecodingStrategy.
5. Pose Estimation: pose::estimate_tag_pose recovers 6-DOF transforms using IPPE or weighted LM.

Examples

use locus_core::{Detector, DetectorConfig, DetectOptions, TagFamily, ImageView};

// Create a detector with default settings
let mut detector = Detector::new();

// Create a view into your image data (zero-copy)
let pixels = vec![0u8; 640 * 480];
let img = ImageView::new(&pixels, 640, 480, 640).unwrap();

// Detect tags (default family: AprilTag 36h11)
let detections = detector.detect(&img);

for detection in detections {
    println!("Detected tag {} at {:?}", detection.id, detection.center);
}

Re-exports

pub use crate::config::DetectOptions;

pub use crate::config::DetectorConfig;

pub use crate::config::TagFamily;

pub use crate::decoder::family_to_decoder;

pub use crate::image::ImageView;

Modules

config

Configuration types for the detector pipeline. Configuration types for the detector pipeline.

decoder

Tag decoding traits and implementations. Tag decoding, homography computation, and bit sampling.

dictionaries

Tag family dictionaries (AprilTag, ArUco). Tag family dictionaries.

filter

Edge-preserving filtering for small tag detection. Edge-preserving filtering for improved small tag detection.

gradient

Gradient computation for edge refinement. Gradient computation for edge-based quad detection.

image

Image buffer abstractions. Stride-aware image view for zero-copy ingestion.

pose

3D Pose Estimation (PnP). 3D Pose Estimation (PnP) for fiducial markers.

pose_weighted

Weighted pose estimation logic.

quad

Quad extraction and geometric primitives. Quad extraction and geometric primitive fitting.

segmentation

Connected components labeling using Union-Find. Connected components labeling (CCL) using Union-Find.

strategy

Decoding strategies (Hard vs Soft). Pluggable decoding strategies for different SNR conditions.

test_utils

Utilities for testing and synthetic data generation.

threshold

Adaptive thresholding implementation. Adaptive thresholding and image binarization.

Structs

Detection

Result of a tag detection.

Detector

The main entry point for detecting AprilTags.

FullDetectionResult

Full result of a detection including intermediate data for debugging.

PipelineStats

Statistics for the detection pipeline stages. Pipeline-wide statistics for a single detection call.

Functions

core_info

Returns version and build information for the core library.