Tutorials

What Gets Installed

Running sima-cli install neat installs two things:

1. The Neat library (the sima-neat package). Goes system-wide via apt. You never interact with it directly — your code links against it through CMake's find_package(SimaNeat CONFIG).

2. The tutorials (the SiMa Neat extras option, opt-in during install). Does not go into system paths. It extracts as a self-contained folder in your current working directory, looking like this:

   sima-neat-0.0.0+<branch>-<sha>-Linux-extras/
   ├── build.sh                      ← build helper (auto-detects extras layout)
   ├── lib/
   │   └── sima-neat/
   │       └── tutorials/            ← prebuilt C++ binaries (tutorial_*)
   └── share/
       └── sima-neat/
           └── tutorials/            ← source folders (.cpp, .py, README.md)

The folder name includes the Neat version, branch, and commit hash. For example, if you ran the installer from ~/neat/, the folder ends up at ~/neat/sima-neat-0.0.0+<branch>-<sha>-Linux-extras/.

When prompted during install, select SiMa Neat extras (press Space to toggle the checkbox) to receive this folder. If you skip it, only the library gets installed and the tutorials are not on disk.

How to Run Tutorials

Everything happens inside the extras folder. cd into it first:

cd sima-neat-*-Linux-extras

Your shell's current directory is now the root of the extras tree. All tutorial commands below use paths relative to here.

Tutorial models

Some chapters need Model Zoo MPKs. build.sh reads the tutorial metadata and the installed dependency manifest, then downloads the right model versions for your platform. By default, models are prepared under /tmp.

When you build C++ tutorials from source, models are downloaded automatically before the build:

./build.sh --target tutorial_<chapter_name>

If you want to prepare models without rebuilding tutorials, run:

./build.sh --download-models-only

To use a different download root, add --model-target-folder <path>.

Verify the install

Both lists should print the same set of chapter names. If either is empty, re-run sima-cli install neat and make sure SiMa Neat extras is selected.

ls lib/sima-neat/tutorials/ | grep '^tutorial_'
ls share/sima-neat/tutorials/ | grep -E '^0[0-9]{2}_'

Activate the pyneat virtual environment before running any Python tutorial:

source ~/pyneat/bin/activate

Python

Python tutorials are interpreted — there's nothing to compile. Run the script directly:

python3 share/sima-neat/tutorials/<chapter>/<chapter_name>.py --args

Copy the .py anywhere on disk if you want to modify it — the same command works from any location.

C++ — run the prebuilt

Every chapter ships as a compiled binary. Run it straight from lib/:

./lib/sima-neat/tutorials/tutorial_<chapter_name> --args

C++ — build from source with build.sh

If you want to recompile a chapter (to tweak it, or because the shipped binary does not match your runtime), run the bundled helper:

./build.sh --list-targets
./build.sh --target tutorial_<chapter_name>
./build/tutorials-standalone/tutorial_<chapter_name> --args

build.sh auto-detects SimaNeatConfig.cmake from the installed Neat package, invokes CMake for the whole tutorials/ tree (or a single target), and writes the binaries under build/tutorials-standalone/. No flags required for a stock Neat SDK or on-device apt install.

C++ — integrate Neat into your own project

Copying a chapter's .cpp into your own codebase? Drop this minimal CMakeLists.txt alongside it — no extras folder required, only the base sima-neat package (which provides libsima_neat.a and SimaNeatConfig.cmake):

cmake_minimum_required(VERSION 3.16)
project(my_chapter LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(SimaNeat REQUIRED CONFIG)

add_executable(my_chapter <chapter_name>.cpp)
target_link_libraries(my_chapter PRIVATE SimaNeat::sima_neat)

Build and run:

cmake -S . -B build && cmake --build build -j
./build/my_chapter --args

find_package(SimaNeat REQUIRED CONFIG) auto-resolves headers, library, and dependencies from the installed Neat — no hardcoded paths, no extras folder required.

For the full template with SYSROOT handling (cross-builds from inside the Neat SDK container), see the Hello Neat Minimal Example.

Use these tutorials in order. Each card links to a chapter with concept-first guidance and matching C++ and Python implementation.

Beginner

Run Your First Model <5 minutes

Load a compiled ResNet-50 MPK, feed it an image, and read the top-1 class in three lines of Python. This is the shortest path...

modelmpkinferencefoundations

Run Inference Asynchronously 10-15 minutes

Feed a model from a producer thread while consuming predictions from another — decouple input and output for real throughput....

asyncpush-pullthroughputruntime

Build an Inference Pipeline 5 minutes

Compose a `Session` by hand — input node, output node, no model — and run one frame through it. See the pipeline primitives i...

sessionbuildrunpipeline

Configure Model Options 5 minutes

`ModelOptions` declares the runtime contract between your input data, the model pipeline stages, and output decoding. It is t...

model-optionsconfigurationcontracts

Intermediate

Preprocess Images Before Inference 15-20 minutes

Configure the preprocessing stage — format, dimensions, and per-channel normalization — so raw image input becomes the exact...

preprocessingnormalizationimage

Read Detection Boxes from Model Output 15-20 minutes

Decode raw model output into usable bounding boxes using `SimaBoxDecode` — thresholding, NMS, and coordinate mapping built in...

postprocessingboxdecodedetection

Plug a Model Into Your Pipeline 15 minutes

Three ways to drop a model into a `Session` — direct node composition, `model.session()`, and `model.session(options)` — so y...

sessioncompositionpatterns

Pass NumPy Arrays to the Model 10-15 minutes

Move data between Neat tensors and the data structures Python users already have — NumPy arrays and PyTorch tensors — without...

numpypytorchtensorio

Feed Models That Take Multiple Inputs 15 minutes

Bundle multiple tensors into one `Sample` and push it as a single inference event. This is the pattern you need when a model...

multi-inputsamplessync

Read and Interpret Model Output 10-15 minutes

Read back from `run.pull()` or `model.run()` safely. Every model returns a `Sample`, but `Sample` is a small sum type — a ten...

outputpatternssink

Diagnose and Profile a Pipeline <10 minutes

Run three checks — `session.validate()`, one metrics-enabled `run.run()`, and `run.stats()` + `run.report()` — to answer whet...

diagnosticsdebuggingobservability

Build a Custom Data Graph 15-20 minutes

Build the smallest useful Neat graph — one pipeline node wired to one stage node — then push a sample through and verify meta...

graphtraversalmetadata

Consume a Live RTSP Stream 5-10 minutes

Attach a live H.264 RTSP stream to a `Session` with the `RtspDecodedInput` node group. The group handles RTSP connect, depack...

rtspstreaminginput-grouplive-input

Advanced

Embed a Model Inside a Graph 20-25 minutes

Drop a model into a graph as a single stage using `stage_model_executor`. This is the bridge pattern when you need graph-leve...

graphhybridstage-modelmpk

Run Multiple Streams in One Graph 20-25 minutes

Schedule multiple streams through one graph — fair scheduling, fan-out branches, and deterministic bundle re-join. This is th...

graphmultistreamschedulerjoin

Tune Throughput and Queue Depth 15-20 minutes

Tune three knobs that control async pipeline behavior under load — queue depth, overflow policy, metrics — and read back what...

performancetuningasyncqueues

Build a Production-Ready Pipeline 20-25 minutes

Assemble a production-style run loop from the patterns earlier chapters taught: explicit `ModelOptions`, explicit `ModelSessi...

productionreliabilitydeployment