DX-APP DX Tool Guide
This guide is intended for contributors and maintainers working on the DX-APP example repository.
./scripts/dx_tool.sh is the unified developer entry point for repetitive example maintenance tasks such as model onboarding, package extraction, example discovery, validation, execution, and benchmarking.
Overview
The tool provides both:
- Interactive mode for guided workflows
- Command mode for repeatable developer operations and automation
Primary script:
./scripts/dx_tool.sh
Related helper scripts:
./scripts/add_model.sh./scripts/extract_model_package.sh./scripts/extract_sln_package.bat./scripts/validate_models.sh./scripts/run_examples.sh./scripts/bench_models.sh
Key data files:
./config/model_registry.json— model registry, single source of truth
When to Use dx_tool.sh
Use dx_tool.sh when you need to:
- add a new example model to the repository structure
- inspect existing models by task or keyword
- extract a standalone package into the current example layout
- validate example assets and generated code structure
- run a filtered subset of examples
- benchmark examples across C++ and Python variants
For end-user installation, setup, and basic inference execution, refer to the installation and usage documents instead of this guide.
Quick Start for Contributors
Step 1. Full Developer Sequence
If you are adding or refactoring an example, follow this standard sequence to ensure everything is built and tested correctly
# 1. Prepare assets & Build
./setup.sh
./build.sh --clean
# 2. Inspect & Validate repository state
./scripts/dx_tool.sh list
./scripts/dx_tool.sh validate
# 3. Run and Verify (C++ and/or Python)
./scripts/dx_tool.sh run --lang both
./run_tc.sh --cpp --cli
./run_tc.sh --python
This sequence prepares assets, rebuilds the repository, inspects available models, validates layout consistency, and performs a fast example-oriented test pass.
Step 2. Execution Modes
Interactive mode
Run the tool with no subcommand to enter the guided menu.
./scripts/dx_tool.sh
This mode is useful when:
- you are exploring the repository for the first time
- you do not remember the exact subcommand
- you want menu-based task selection
dx_tool.sh run with no arguments delegates to scripts/run_examples.sh interactive mode, which provides a 6-stage guided menu (language, category, model filter, sync/async, input type, display/save options) with a configuration summary before execution. Each test also displays its performance table.
Command mode
Run a subcommand directly when you already know the intended task.
./scripts/dx_tool.sh list
./scripts/dx_tool.sh search yolov9
./scripts/dx_tool.sh validate
This mode is better for:
- repeatable contributor workflows
- shell history reuse
- scripting and CI-friendly operations
Step 3. Command Summary
| Command | Purpose |
|---|---|
add | Create a new model/example skeleton |
extract | Extract a standalone package into repository layout |
list | List registered models |
search | Search models by keyword |
info | Show model details |
delete | Remove a model from the repository |
new-task | Create a new task directory skeleton |
validate | Validate current model/example layout |
run | Execute examples with filters |
bench | Benchmark examples with filters |
help | Show usage help |
Core Capabilities & Reference
Model Management
Model Registry
config/model_registry.json is a JSON array that serves as the single source of truth for all model metadata. Each entry contains:
| Field | Purpose |
|---|---|
model_name | Unique identifier (e.g., yolov9s) |
dxnn_file | Compiled model filename (e.g., YOLOV9S.dxnn) |
add_model_task | Task category (e.g., object_detection) |
postprocessor | Which shared processor to use (e.g., yolov8) |
input_width, input_height | Model input dimensions |
config | Extra parameters (thresholds, num_classes, etc.) |
supported | Whether the model is part of the standard validation flow |
The add command reads this registry to auto-generate factory files, config.json, and all entry-point scripts.
Adding Examples
- Use
addwhen you are onboarding a new model into an existing task category. - Use
new-taskwhen you are introducing a new task-level grouping that does not yet exist in the current repository layout.
In both cases, validate the result and then update the related test registration if the example should be covered by automated tests.
Validation & Verification
Basic validation
./scripts/dx_tool.sh validate
# or directly:
./scripts/validate_models.sh --lang py
This runs code generation + NPU inference for all supported models.
validate_models.sh options
| Option | Purpose |
|---|---|
--lang cpp|py|both | Language filter |
--skip-verify | Code generation only (no inference) |
--no-video | Image-only mode |
--list | Print commands without executing |
--clean | Remove all generated packages |
--start-from <model> | Resume from a specific model |
<task_filter> | Filter by task (e.g., object_detection) |
Execution & Benchmarking
-
Selective Run: The
runcommand abstracts the complexity of finding specific binaries. It uses filters to execute subsets of the 130+ models instantly. -
Performance Benchmarking: The
benchcommand runs models in a loop, calculating average latency and throughput (FPS) while minimizing system noise.
Common Workflows
Step 1. New Model/Task Integration
Step 1-1. Discover existing examples
./scripts/dx_tool.sh list
./scripts/dx_tool.sh search yolov8
./scripts/dx_tool.sh info yolov9
Use this first to avoid creating duplicate or inconsistent example names.
Step 1-2. Add a new model example
./scripts/dx_tool.sh add
The add flow is intended for contributors creating a new example under the current task/model layout. Typical information includes:
- target language (
cpp,py, or both) - task category
- model name
- post-processing selection
- sync-only or multi-variant generation choice
You can also invoke add_model.sh directly for non-interactive usage:
For YOLO-family model onboarding and postprocessor selection details, refer to DX-APP YOLO Customizing Guide.
# Create from a postprocessor template
./scripts/add_model.sh yolov30 detection --postprocessor yolov8
# Copy from an existing model directory (useful for same-family variants)
./scripts/add_model.sh yolov7_w6 detection --base-model yolov7 --postprocessor yolov7
# Generate, verify, and push in one step
./scripts/add_model.sh yolov30 detection --postprocessor yolov8 --verify --model assets/models/YoloV30.dxnn --git-push
Common --postprocessor values include:
| Task | Common values |
|---|---|
| Object detection | yolov5, yolov7, yolov8, yolov9, yolov10, yolov11, yolov12, yolov26, yolox, damoyolo, nanodet, ssd |
| Semantic segmentation | deeplabv3, bisenetv1, bisenetv2, segformer, fast_segmentation |
| Instance segmentation | yolov5seg, yolov8seg, yolov26seg |
| Pose estimation | yolov5pose, yolov8pose, yolov26pose |
| Face detection | scrfd, yolov5face, yolov7face |
Use fast_segmentation for generic semantic-segmentation models that output low-resolution logits or class maps and should use the FastSegmentationPostprocessor fast path.
Key add_model.sh options
| Option | Description |
|---|---|
--postprocessor <type> | Select the post-processing family to use as template |
--base-model <name> | Copy from a specific existing model directory instead of the default reference |
--lang <cpp|py|both> | Target language (default: both) |
--verify | Build and run inference verification after generation |
--model <path> | .dxnn model file for --verify |
--no-video | Skip video verification (image only) |
--git-push | After successful --verify, commit and push |
--auto-add | Batch-generate source packages for all unregistered models |
After generation, review the resulting files under src/cpp_example/ and/or src/python_example/.
Step 1-3. Verify the integration
After generation, verify that the new example is correctly integrated and runs without issues.
# Check if all required files and registry entries are consistent
./scripts/dx_tool.sh validate
# Test the new example (e.g., for C++)
./scripts/dx_tool.sh run --lang cpp --model <your_model_name>
If you used the --verify flag with add_model.sh in the previous step, this manual verification might be redundant but is still recommended for visual confirmation.
Step 2. Packaging & Distribution
Step 2-1. Extract a standalone package
./scripts/dx_tool.sh extract
Use this when you need to convert an external model package into the repository layout used by DX-APP.
Step 2-2. Extract a Visual Studio solution package on Windows
Use extract_sln_package.bat when you want to extract a single C++ example into a Visual Studio/CMake package that can be opened or built outside the full DX-APP solution.
.\scripts\extract_sln_package.bat classification/resnet50 --output-dir out_resnet50
The output is created under:
out_resnet50\sln\classification\resnet50\
If CMake and the Visual Studio 2022 generator are available, the extractor also configures the package immediately and generates a solution file:
out_resnet50\sln\classification\resnet50\build\dxapp_resnet50_sln_package.sln
The package includes the selected model sources, shared C++ example helpers, CMakeLists.txt, build.bat, and generated dependency defaults. To build it directly:
cd .\out_resnet50\sln\classification\resnet50
.\build.bat
OpenCV and DXRT paths are configured through CMake. The extractor writes the dependency defaults it can detect at extraction time to:
cmake\dxapp_package_deps.cmake
cmake\dxapp_package_deps.bat
In the usual local developer environment, users should not need to edit Visual Studio property pages manually. If the package is moved to another PC or dependency paths change, set one of these variables before running build.bat, or edit cmake\dxapp_package_deps.cmake:
| Variable | Purpose |
|---|---|
DXRT_DIR | DXRT SDK root |
DXRT_INSTALLED_DIR | DXRT install root used for include, lib, and bin |
OpenCV_DIR | OpenCV CMake package directory |
VCPKG_INSTALLED_DIR | vcpkg installed tree used for runtime DLL lookup |
To create only the package skeleton without configuring CMake or generating .sln files:
.\scripts\extract_sln_package.bat classification/resnet50 --output-dir out_resnet50 --no-generate-sln
Step 3. Repository Maintenance
Step 3-1. Validate repository consistency
./scripts/dx_tool.sh validate
Run validation after adding or restructuring examples. This helps catch mismatched files, missing variants, or incomplete model onboarding.
Step 3-2. Run examples selectively
# Interactive — guided category/model selection with performance output
./scripts/dx_tool.sh run
scripts/run_examples.sh
# Non-interactive
./scripts/dx_tool.sh run --lang cpp
./scripts/dx_tool.sh run --lang py
./scripts/dx_tool.sh run --lang both
Use run to execute filtered example sets without manually locating every command.
In interactive mode, selecting a category shows all available models in that category.
Step 3-3. Benchmark examples
./scripts/dx_tool.sh bench --lang cpp
./scripts/dx_tool.sh bench --lang py
Use bench when you want comparable runtime results across example variants.
Notes for Automation
For CI or scripted usage:
- prefer direct subcommands over interactive mode
- keep
dx_tool.shfor contributor automation, not end-user setup - use
setup.sh,build.sh, andrun_tc.shfor deterministic pipeline steps
Supplementary Information
Script Relationships
dx_tool.sh is a developer workflow tool, not a replacement for every top-level script.
setup.sh: prepares shared assets such as models and videosbuild.sh: builds C++ binaries and Python bindingsrun_tc.sh: runs the repository test suitesscripts/dx_tool.sh: helps contributors add, inspect, validate, run, and benchmark example content
A typical contributor workflow is:
- (1) prepare assets with
./setup.sh - (2) build binaries with
./build.sh - (3) inspect or add examples with
./scripts/dx_tool.sh - (4) run validations and tests with
./scripts/dx_tool.sh validateand./run_tc.sh
FAQ & Troubleshooting
The exact workflow depends on the contributor task, but the following command patterns are the most commonly used.
Inspect the current repository state
./scripts/dx_tool.sh list
./scripts/dx_tool.sh search yolov8
./scripts/dx_tool.sh info yolov9
Validate after adding or refactoring examples
./scripts/dx_tool.sh validate
Run language-specific example subsets
# Interactive — 6-stage guided menu
./scripts/dx_tool.sh run
scripts/run_examples.sh
# Non-interactive — pass options directly
./scripts/dx_tool.sh run --lang cpp
./scripts/dx_tool.sh run --lang py
./scripts/dx_tool.sh run --lang both
Benchmark language-specific example subsets
./scripts/dx_tool.sh bench --lang cpp
./scripts/dx_tool.sh bench --lang py
See Also
scripts/dx_tool.shscripts/add_model.shscripts/validate_models.shscripts/run_examples.shscripts/bench_models.shconfig/model_registry.jsondocs/11_DX-APP_Example_Source_Structure.md