Run custom trained data models. This package includes MobileNet SSD COCO model. The idea is to replace this model with your own. Please read Train-Build.md to understand how to train and build the package.
Pre-compiled .eap packages are published by GitHub Actions. Download the latest pre-compiled package here:
- For the latest tagged version, open the repository's Releases page and download the versioned
.eapfile from the release assets. - For test builds, open the Actions tab, select the latest "Build EAP Package" run, and download the
detectx-<version>-eapartifact.
Maintainers can publish a new release package by pushing a version tag, for example git tag v4.1.1 && git push origin v4.1.1.
- Clone the repository
- Replace the model and labels (if using your own):
- Place your TFLite model at
app/model/model.tflite - Place your labels file at
app/model/labels.txt
- Place your TFLite model at
- Run the build script:
./build.sh
- Install the generated
.eapfile on your Axis camera
Note: As of version 4.0.0, the prepare.py script is no longer required. Model parameters are now automatically extracted during the build process.
DetectX is a versatile ACAP (Axis Camera Application Platform) for on-camera, real-time object detection, supporting various detection tasks depending on the bundled model.
Below are model-specific details relevant to the generic "COCO" demo:
| Variant | Dataset | Labels | ARTPEC-8 | ARTPEC-9 |
|---|---|---|---|---|
| DetectX COCO | COCO | person, bicycle, car, motorcycle, airplane, bus, train, truck, boat, traffic light, fire hydrant, stop sign, parking meter, bench, bird, cat, dog, horse, sheep, cow, elephant, bear, zebra, giraffe, backpack, umbrella, handbag, tie, suitcase, frisbee, skis, snowboard, sports ball, kite, baseball bat, baseball glove, skateboard, surfboard, tennis racket, bottle, wine glass, cup, fork, knife, spoon, bowl, banana, apple, sandwich, orange, broccoli, carrot, hot dog, pizza, donut, cake, chair, couch, potted plant, bed, dining table, toilet, TV, laptop, mouse, remote, keyboard, cell phone, microwave, oven, toaster, sink, refrigerator, book, clock, vase, scissors, teddy bear, hair drier, toothbrush | Model input: 640 Model size: Small |
Model input: 640 Model size: Small |
Note: ARTPEC-8 and ARTPEC-9 are Axis camera chipset platforms, with ARTPEC-9 offering enhanced performance and the ability to process larger images for improved detection quality.
DetectX provides real-time detection and state data from network cameras directly to your systems. Intended for system integrators, all outputs are designed for machine-to-machine (M2M) workflows, with flexible configuration from a built-in web UI and standards-based output via MQTT, ONVIF, or HTTP.
Typical use cases include:
- Vehicle and person detection in perimeter security
- Counting and presence analytics
- Intelligence enrichment for video management systems (VMS) or IoT platforms
Each menu item below describes both user options and integration outputs, matched to the associated interface screenshot for easy visual orientation.
Allows you to see object detections overlayed on the video, and to adjust detection parameters.
- Adjust Confidence Threshold:
Set the minimum confidence (0–100) for labeling a detection as valid. - Set Area of Interest (AOI):
Draw a polygon to receive detections only from the area inside the polygon. Click to add vertices; drag vertices to reshape. - Add Exclude Zones:
Draw one or more exclude polygons to suppress detections in specific areas (e.g. tree, reflection, road sign). Multiple zones are supported. - Configure Minimum Object Size:
Exclude detections smaller than the specified pixel area.
Visualization Notes:
- The overlay updates approximately two times per second (“best effort”). The bounding boxes may lag or not exactly match all detections due to UI and network constraints.
- Use this page for quick confirmation that detection is working and properly tuned.
Here you configure the gateway between the camera and your backend system.
- Broker Address and Port:
Specify the IP or hostname for your MQTT broker and port (default: 1883). - Authentication:
Optional username and password if security is enforced. - Pre-topic:
The prefix added to all MQTT topics (e.g.,detectx/detection/...). Change if routing multiple cameras. - Additional Metadata:
Name and Location properties help you distinguish events in multi-camera setups.
Connection Status is displayed, along with currently active parameters for fast troubleshooting.
This section allows you to tailor detection and event signaling to your application:
- Selectable Labels:
Check or uncheck which object types (labels) are actively processed, reducing false positives or narrowing the scope (e.g., only cars and persons). - Event State Settings:
- Prioritize: Opt for accuracy (suppresses false triggers) or responsiveness.
- Minimum Event State Duration: Avoid chattering by forcing a minimum active/inactive state period for each label.
- SD Card Training Capture:
When enabled, full-frame JPEG images and matching YOLO-format label files are saved to the SD card whenever a detection event is active. Images are captured at a configurable interval (1–60 s); the first image is captured immediately on the event going active. A Download Archive button packages all captured images and labels into a zip file ready for import into your training pipeline. A Clear All button removes all stored files. Capture stops automatically at 2 000 images to protect SD card space.
Note:
Each label produces an independent event state. Tuning event parameters is crucial for noisy or high-traffic scenes.
When downstream systems require not only detection data but cropped images for each detection:
- Enable/Disable Detection Cropping
- Set Border Adjustment:
Expand or shrink the crop region around detected objects (e.g., add 25px margin). Presets available for common use cases. - Output Methods:
- MQTT: Sends cropped images as base64 payloads.
- HTTP POST: Posts the payload to a configurable endpoint.
- Throttle Output:
Limit image frequency to reduce load or network traffic.
A dashboard combining:
- Model Status: Input size, inference time, DLPU backend, and status.
- Device Details: Camera type, firmware, serial, CPU & network usage.
- MQTT Status: Broker and topic configuration, connection health.
- Application Info: Name, version, vendor, support/documentation link.
Use this page as your first check when troubleshooting or confirming installation.
DetectX delivers three primary payload types, all enrichable with the configured device name, location, and serial for easy association in your backend systems.
Topic:
detectx/detection/<serial>
Example Payload:
{
"detections": [
{
"label": "car",
"c": 77,
"x": 274,
"y": 224,
"w": 180,
"h": 104,
"timestamp": 1756453942980,
"refId": 260
}
],
"name": "Front",
"location": "",
"serial": "B8A44F3024BB"
}Topic:
detectx/event/<serial>/<label>/<state>
Example Payload:
{
"label": "car",
"state": false,
"timestamp": 1756453946184,
"name": "Front",
"location": "",
"serial": "B8A44F3024BB"
}MQTT/HTTP Topic or POST:
detectx/crop/<serial>
Example Payload:
{
"label": "truck",
"timestamp": 1756454378759,
"confidence": 47,
"x": 25,
"y": 25,
"w": 218,
"h": 106,
"image": "/9j/4AAQSk...", // JPEG in Base64
"name": "Front",
"location": "",
"serial": "B8A44F3024BB"
}- Start with the About page to confirm firmware, model, and MQTT status before field adjustments.
- Use Detection and Crops pages for rapid troubleshooting—verify detections visually before integrating triggers or actions.
- Use unique device names/locations in MQTT setup for scalable multi-camera deployments.
- Adjust event suppression and AOI settings based on site/scene context for best accuracy.
- If bounding boxes do not appear but the model status is OK, check confidence, AOI, and MQTT broker configuration.
- If crop images are misaligned or cut-off, adjust crop borders and AOI, validating via the “View the latest crops” gallery.
- Monitor CPU and network on the About page to avoid overload (especially on ARTPEC-8 devices).
- Polygon Area of Interest: The AOI is now defined as a free-form polygon instead of a rectangle. Click on the AOI canvas to add vertices and drag them to any shape. The area outside the polygon is dimmed so the active zone is immediately visible.
- Polygon Exclude Zones: Multiple exclude zones can be drawn as polygons. Each zone suppresses detections inside it, useful for masking persistent false-positive areas such as trees, reflections, or road signs.
- Upload Custom Model: A new Model page lets you upload a replacement
.tflitemodel file andlabels.txtdirectly from the browser — no SSH or Docker rebuild required. - SD Card Training Capture: Configurable event-driven capture of full-frame JPEG images and YOLO-format label files to the SD card, designed for collecting site-specific training data for model fine-tuning. Includes a Download Archive button (zip of
images/+labels/) and a Clear button. Capture triggers immediately when a detection event goes active, then repeats at a user-defined interval (1–60 s). Stops automatically at 2 000 images. - Bounding-Box Overlay Accuracy: Reworked canvas/video alignment for all scale modes (center-crop, balanced, letterbox) so detection overlays are pixel-accurate regardless of browser window size.
- Border preset buttons on the Detection Export page for common crop-margin adjustments.
- Polygon vertices are clamped to the canvas boundary during drag.
- Polygon drag operations complete correctly even when the mouse is released outside the canvas.
- Pixel-Based Coordinate System: Complete redesign from normalized [0-1000] coordinates to native pixel coordinates matching model input dimensions
- 1:1 Display Aspect Ratio: All scale modes now display in model-sized 1:1 view (typically 640x640) for "what you see is what you get" visualization
- Enhanced Scale Mode Support: True visual representation for each mode:
- Center-Crop: 640x640 1:1 video with no black bars
- Balanced: 856x640 (4:3 aspect) squeezed into 1:1 display
- Letterbox: 1136x640 (16:9 aspect) displayed in 1:1 with visible padding
- Modern UI Redesign: Complete redesign with top navigation bar replacing sidebar, modern card-based layouts, and improved visual hierarchy
- Simplified Build Process: Removed dependency on
prepare.py- model parameters now automatically extracted during Docker build
- Pixel Coordinates Throughout: All coordinates (detections, AOI, size filters) now use pixels relative to model input dimensions
- MQTT Metadata: Detection payloads now include
metadataobject withmodelWidth,modelHeight, andcoordinateSystem: "pixels"for client compatibility - Automatic Settings Migration: Existing configurations automatically migrate from normalized to pixel coordinates via
coordinateVersionflag - Direct Model-to-Display Mapping: Simplified coordinate transformation eliminates multi-stage conversions and aspect ratio calculations
- Optimized Resolutions: Balanced mode uses 856x640 (4:3) to maximize 640px height while maintaining divisibility by 8
- Resolution Strategy: Center-crop (640x640), Balanced (856x640), Letterbox (1136x640) - all optimized for model input size
- Improved Memory Efficiency: Direct pixel scaling reduces processing overhead
- Custom AOI Overlay: Removed jQuery imgAreaSelect plugin (944 lines), implemented lightweight custom overlay with mouse drag handlers
- Canvas Alignment: Perfect pixel-accurate alignment of detection overlays with video for all scale modes
- Gradient Navigation Bar: Improved contrast and readability with modern design
- Responsive Design: Optimized for mobile, tablet, and desktop viewing
- Improved Form Controls: Better focus states and validation feedback
- Direct Pixel Conversion: Model outputs converted directly to pixels instead of intermediate [0-1000] normalization
- Removed Display Space Transformations: Eliminated videoAspect-based coordinate scaling simplifies codebase
- Enhanced Crop Generation: Crops use pixel-based scaling from model space to video frame space
- Settings Migration: Automatic one-time migration from coordinateVersion 1 to 2
- Improved MQTT Payload Handling: Better error messages for oversized crops
- Fixed coordinate misalignment in all scale modes with pixel-accurate canvas positioning
- Resolved letterbox mode canvas stretching by using calculated pixel dimensions
- Fixed canvas clearing to use actual dimensions instead of hardcoded values
- Improved video and overlay synchronization with object-fit strategies
- MQTT Output Format: Coordinates now in pixels with metadata (breaking for API consumers)
- Coordinate System: Changed from normalized [0-1000] to pixels (coordinateVersion: 2)
- Display Aspect: Changed from 16:9 to 1:1 aspect ratio for all visualizations
- Settings Format: AOI and size filters now use pixel coordinates (automatic migration on first startup)
- API Clients: MQTT consumers need to detect
metadata.coordinateSystem === "pixels"and scale accordingly
- Updated
CLAUDE.mdwith coordinate system architecture - Added comprehensive implementation plan documentation
- Updated README with simplified build instructions
- Fixed a memory leak
- Fixed "black-box-video" shown on selected cameras
- Added Detection Export
- Updated GUI
- MQTT improvements
- MQTT Cleanup
- GUI fixes
- Fixed IP address in MQTT connect message.
- MQTT Refactoring
- Fixed a flaw in html that crashed the detections page (stupid bug introduced in previous version)
- Fixed MQTT stability (recurring disconnects)
- Added MQTT connect message and more properties in LWT
- Fixed MQTT stability (recurring disconnects)
- Improved behaviour in GUI
- Display error when not running on ARTPEC-8 (e.g. Ambarella CV25)
- Display info when model is loading
- Display info when application not responding
- Fixed a bug that could crash the application if the user interface is active for a longer period of time.
(Credit to Fredrik Lax, Sundsvall-IT who found it)
- Fixed a serious memory leak
- Restructured and added more information on the About page
- Added support for MQTT
- Bumbed ACAP wrapper up to 3.2.0
- Fixed a flaw that impact events.
- Switched to latest ACAP SDK. Please remove previous version if they are below 3.0.0.
- Refactoring on various files
- Modified events to give all labels its own event
- Updated visualization in user interface
- Added event "Label Counter" for use cases needing to know how many objects are detected
- Fixed flaw for Detection transition
- Fixed flawed event states
- Fixed potential memoryleak
- Added support for Detection transition
- Removed ability to store detectection images on SD Card
- Added support fo filter minimum size
- Fixed a flaw that preventet detecting mutliple detections in the same scene.
- Restructures the model.json and settings.json and code realted to those config files including prepare.py
- Fixed flaw that prevented detections
- Fixed flaw that did not store images on SD Card when users enabled this feature
- Restructured SD Card image store on detect images. Fix a flaw that could result in error "Too many files open...".
- Fixed so Reset button cleared all bounding boxes and table
- Initial commit