Plug a Model Into Your Pipeline

Field	Value
Difficulty	Intermediate
Estimated Read Time	15 minutes
Labels	session, composition, patterns

Concept

Three ways to drop a model into a Session — direct node composition, model.session(), and model.session(options) — so you know which pattern fits which context. All three produce a runnable session; they differ in explicitness and control.

The three composition patterns shown:

• Direct session: add Input + Output nodes yourself with session.add(...). Most explicit; useful when you need full control over the wiring.
• Model-default session: model.session() injects the model's default pipeline group with sensible defaults. Shortest path for most cases.
• Model-attached session: model.session(ModelSessionOptions) controls appsrc/appsink inclusion and stage naming when attaching model groups into larger pipelines.

Why this matters:

• Teams often start with direct sessions for clarity, then move to model-backed composition as systems scale.
• ModelSessionOptions keeps graph wiring explicit in multi-camera or multi-model deployments.
• Consistent naming (upstream_name, name_suffix, buffer_name) improves diagnostics and backend graph readability.

APIs introduced

• model.session() — inject the default model pipeline.
• pyneat.ModelSessionOptions() + model.session(opts) — attach with explicit options.
• session.add(group_or_node) — what all three patterns reduce to underneath.

Prerequisites Chapter 001 (Model). Chapter 002 or 003 (Session basics).

References

• Session
• Model

Learning Process

1. Build a minimal direct session and validate it can run end-to-end.
2. Construct model-backed session variants (model.session() and model.session(options)).
3. Compare generated backend graphs with --print-gst to understand composition differences.

Run

Python:

python3 share/sima-neat/tutorials/007_plug_model_into_pipeline/plug_model_into_pipeline.py \
  --mpk /tmp/yolo_v8s_mpk.tar.gz

C++ (prebuilt):

./lib/sima-neat/tutorials/tutorial_007_plug_model_into_pipeline \
  --mpk /tmp/yolo_v8s_mpk.tar.gz

C++ (build from source):

./build.sh --target tutorial_007_plug_model_into_pipeline
./build/tutorials-standalone/tutorial_007_plug_model_into_pipeline \
  --mpk /tmp/yolo_v8s_mpk.tar.gz

To integrate this chapter's C++ source into your own project with a custom CMakeLists.txt (no extras folder required), see How to Run Tutorials on the landing page.

Code

tutorials/007_plug_model_into_pipeline/plug_model_into_pipeline.cpp

// Three Session composition patterns: direct nodes, model.session(), attached session.
//
// Usage:
//   tutorial_007_plug_model_into_pipeline [--mpk /path/to/model.tar.gz]

#include "neat.h"

#include <opencv2/core.hpp>

#include <filesystem>
#include <iostream>
#include <stdexcept>
#include <string>

namespace fs = std::filesystem;

namespace {

bool get_arg(int argc, char** argv, const std::string& key, std::string& out) {
  for (int i = 1; i + 1 < argc; ++i) {
    if (key == argv[i]) {
      out = argv[i + 1];
      return true;
    }
  }
  return false;
}

} // namespace

int main(int argc, char** argv) {
  try {
    const int width = 224;
    const int height = 224;

    cv::Mat rgb(height, width, CV_8UC3, cv::Scalar(80, 40, 160));
    if (!rgb.isContinuous())
      rgb = rgb.clone();

    // Pattern 1: build a Session by adding Input/Output nodes directly.
    simaai::neat::InputOptions in;
    in.format = "RGB";
    in.width = width;
    in.height = height;
    in.depth = 3;
    in.do_timestamp = true;

    // CORE LOGIC
    simaai::neat::Session direct;
    direct.add(simaai::neat::nodes::Input(in));
    direct.add(simaai::neat::nodes::Output());

    std::string mpk;
    if (get_arg(argc, argv, "--mpk", mpk) && fs::exists(mpk)) {
      simaai::neat::Model model(mpk);

      // Pattern 2: ingest the model's default session group.
      // CORE LOGIC
      simaai::neat::Session from_model;
      from_model.add(model.session());
      std::cout << "model_session_size=" << model.session().size() << "\n";

      // Pattern 3: attach the model under an upstream name with custom options.
      simaai::neat::Model::SessionOptions sopt;
      sopt.include_appsrc = false;
      sopt.include_appsink = true;
      sopt.upstream_name = "camera0";
      sopt.name_suffix = "_camera0";
      sopt.buffer_name = "camera0";

      // CORE LOGIC
      simaai::neat::Session attached;
      attached.add(model.session(sopt));
      std::cout << "attached_session_backend=\n" << attached.describe_backend() << "\n";
    }

    auto run = direct.build(std::vector<cv::Mat>{rgb}, simaai::neat::RunMode::Sync);
    simaai::neat::TensorList out = run.run(std::vector<cv::Mat>{rgb}, /*timeout_ms=*/1000);

    if (out.empty())
      throw std::runtime_error("direct session output missing tensor");
    std::cout << "direct_rank=" << out.front().shape.size() << "\n";
    std::cout << "[OK] 007_plug_model_into_pipeline\n";
    return 0;
  } catch (const std::exception& e) {
    std::cerr << "[FAIL] " << e.what() << "\n";
    return 1;
  }
}

Source

• C++
• Python
• README