Skip to navigation

Getting Started

View as Markdown

Welcome to Holoscan SDK 5.0. This Getting Started track takes you from an empty project to a running multi-rate sensor-fusion pipeline: a 60 Hz camera and a high-rate IMU feeding a fusion operator that drives a control output. Each chapter adds exactly one capability, and every chapter’s code builds on the previous one, so by the end you have written — not just read about — a complete application that composes, compiles, and runs.

Application graphs can be authored in C++ or Python. This track’s operator implementation and deep reference chapters are C++ topics; Python applications compose registered C++ operators through discoverable proxies and can define their own operators, as the Python guide describes. The lifecycle and graph chapters show both spellings where the supported surfaces are equivalent.

You will learn
  • How the compose → compile → run model applies in both C++ and Python
  • Which chapters define C++ operators and which also apply to Python applications
  • Where to find runnable examples and language-specific guidance
Camerasource · 60 HzIMUsource · high-rateFusionmulti-rate contractControloutputtutorial pathclock drives the graph

The full track introduces checked errors and time before the sensor-fusion example. C++ compute() returns holoscan::expected<T, Error>; composition mistakes may throw and compilation returns an inspectable plan. Operator timing comes from temporal contracts, including the supported input-driven default when contract() is omitted.

Prerequisites

  • Linux (x86_64 or aarch64).
  • A C++20 toolchain and CMake 4.0 or newer.
  • A CUDA-capable NVIDIA GPU — optional until the final chapter (Tensors 101); everything before it runs on the CPU.
  • The SDK installed — follow SDK installation first if you have not.

The chapter sequence

Work through the chapters in order; each assumes the ones before it.

  1. Core concepts — the three-phase model (compose → compile → run) and the vocabulary the whole guide uses.
  2. Errors as values — holoscan::expected<T, Error>, branching on ErrorCode, and the HOLOSCAN_TRY macro that keeps error-handling readable.
  3. Time and clocks — how the runtime models time, and why every sample carries a timestamp.
  4. Your first operator — an operator as three declarations: setup() for structure, contract() for time, compute() for work.
  5. Typed parameters — declaring configuration with schemas so bad config fails before run.
  6. Composing a graph — wiring operators together through typed ports with add_flow().
  7. Compile and check — compile() turns your composed graph into an execution plan, or returns a rejected plan that tells you exactly why.
  8. Running and stopping — starting the plan, observing it, and shutting down cleanly.
  9. Your first pipeline — assembling the camera + IMU fusion pipeline end to end, with its multi-rate temporal contract.
  10. Tensors 101 — GPU payloads: borrowing tensors from preallocated pools with allocate_tensor(), and why you never synchronize on the hot path.

Why errors and time come first. In Holoscan 5.0, failure handling and temporal behavior are not advanced topics — they are the calling convention. APIs return expected values you must branch on, and compute() never reasons about time because contract() already did. Chapters 2 and 3 give you those two lenses; every chapter after them assumes you have both.

Where to go afterward

When the track is complete, the fusion pipeline you built continues as the running example in Building operators and the full worked applications in Holoscan by example, including the camera_imu_control and slow_fast_fusion example apps that ship with the SDK.

Start with the minimal application

The shipped first_pipeline C++ example demonstrates the complete lifecycle. Build and run it from its cpp/ directory:

cmake -B build -S .
cmake --build build
./build/first_pipeline

For the corresponding Python authoring shape, start with the Python overview. Its snippets use an explicitly installed Operator provider; this source tree does not yet ship a standalone Python sibling for first_pipeline.

Recap

  • C++ and Python applications use the same compose → compile → run lifecycle.
  • C++ and Python both define operators; Python also composes registered C++ operators through discoverable proxies.
  • Start with the language tabs on the graph, compile, and run chapters, then use the Python section for installation and language-specific behavior.