Graph Class
The assembly stage — turns a list of Nodes into a runnable, deterministic pipeline. More...
Declaration
Included Headers
Public Member Typedefs Index
| using | TensorCallback = std::function< bool(const simaai::neat::Tensor &)> |
|
Callback signature used by source-mode pipelines (no input pushed; pipeline produces tensors continuously). More... | |
Enumerations Index
| enum class | CompositionEdgeKind { ... } |
| enum class | SinkRequirement : int { ... } |
Friends Index
| struct | simaai::neat::internal::ModelAccess |
Public Constructors Index
| Graph (const GraphOptions &opt={}) | |
|
Construct an empty Graph with the given options (or defaults). More... | |
| Graph (std::string name, const GraphOptions &opt={}) | |
|
Construct an empty Graph with a label used for diagnostics, save/load, and visualization. More... | |
| Graph (const Graph &)=delete | |
|
Non-copyable. More... | |
| Graph (Graph &&) noexcept | |
|
Move-constructible. More... | |
Public Destructor Index
| ~Graph () noexcept | |
Public Operators Index
| Graph & | operator= (const Graph &)=delete |
|
Non-copyable. More... | |
| Graph & | operator= (Graph &&) noexcept |
|
Move-assignable. More... | |
Public Member Functions Index
| Graph & | set_name (std::string name) |
|
Set the Graph label used for diagnostics, save/load, and visualization. More... | |
| const std::string & | name () const noexcept |
| std::vector< std::string > | inputs () const |
|
Return public logical input endpoint names declared by this Graph. More... | |
| std::vector< std::string > | outputs () const |
|
Return public logical output endpoint names declared by this Graph. More... | |
| Graph & | add (std::shared_ptr< Node > node) |
| Graph & | add (const Graph &fragment) |
| Graph & | add (Graph &&fragment) |
| Graph & | add (const Model &model) |
|
Append a model route as a linear graph fragment. More... | |
| Graph & | connect (std::string_view from_endpoint, std::string_view to_endpoint) |
|
Connect named endpoints or reusable fragments through the public Graph compiler. More... | |
| Graph & | connect (const Graph &from, const Graph &to) |
| Graph & | connect (const Graph &from, const Graph &to, const GraphLinkOptions &options) |
| Graph & | connect (std::shared_ptr< Node > from, std::shared_ptr< Node > to) |
| Graph & | connect (const Graph &from, std::shared_ptr< Node > to) |
| Graph & | connect (std::shared_ptr< Node > from, const Graph &to) |
| Graph & | connect (std::shared_ptr< Node > from, std::string_view from_output, const Graph &to, const GraphLinkOptions &options={}) |
|
Connect one named output pad of a Node to a Graph fragment. More... | |
| Graph & | connect (const Model &from, const Model &to) |
| Graph & | connect (const Model &from, const Graph &to) |
| Graph & | connect (const Graph &from, const Model &to) |
| Graph & | connect (const Model &from, std::shared_ptr< Node > to) |
| Graph & | connect (std::shared_ptr< Node > from, const Model &to) |
| Graph & | custom (std::string fragment) |
|
Splice a raw GStreamer launch fragment into the pipeline. More... | |
| Graph & | custom (std::string fragment, InputRole role) |
|
Variant that declares the fragment's role (e.g., source vs. sink). More... | |
| void | run () |
|
Run a source-mode pipeline (no inputs pushed; producer Nodes drive the flow). More... | |
| TensorList | run (const std::vector< cv::Mat > &inputs, const RunOptions &opt={}) |
|
One-shot synchronous push+pull from cv::Mat inputs. More... | |
| TensorList | run (const TensorList &inputs, const RunOptions &opt={}) |
| Sample | run (const Sample &inputs, const RunOptions &opt={}) |
|
One-shot synchronous push+pull from Sample inputs (carries per-buffer metadata). More... | |
| Run | build (const std::vector< cv::Mat > &inputs, const RunOptions &opt={}) |
|
Build a long-lived async Run handle, seeding caps from cv::Mat inputs. More... | |
| Run | build (const TensorList &inputs, const RunOptions &opt={}) |
| Run | build (const Sample &inputs, const RunOptions &opt={}) |
|
Build variant seeded with full Sample inputs (with per-buffer metadata). More... | |
| GraphReport | validate (const ValidateOptions &opt, const cv::Mat &input) const |
|
Validate the Graph against a real input sample without running the pipeline. More... | |
| RtspServerHandle | run_rtsp (const RtspServerOptions &opt) |
| GraphReport | validate (const ValidateOptions &opt={}) const |
| Graph & | add_output_tensor (const OutputTensorOptions &opt={}) |
|
Append a tensor-friendly output (auto-inserts convert/scale/caps + sink). More... | |
| std::string | describe (const GraphPrinter::Options &opt={}) const |
|
Returns a hierarchical, human-readable view of the Nodes added so far. More... | |
| std::string | describe_backend (bool insert_boundaries=false) const |
|
Returns the GStreamer launch string the Graph would emit at build(). More... | |
| void | set_guard (std::shared_ptr< void > guard) |
|
Attach an external lifetime guard (used by externally-managed runtimes). More... | |
| void | set_tensor_callback (TensorCallback cb) |
|
Set the per-tensor callback used by source-mode run(). More... | |
| void | save (const std::string &path) const |
|
Save the Graph's Node list, options, and topology to a JSON file at path. More... | |
| Run | build (const RunOptions &opt={}) |
|
Build a Graph as an asynchronous runner without seeding inputs. More... | |
| Run | build (std::initializer_list< std::nullptr_t >) |
|
Preserve the established build({}) default-options idiom. More... | |
| const std::string & | last_pipeline () const |
|
Returns the GStreamer launch string from the most recent build() call. More... | |
Private Member Functions Index
| void | invalidate_built_ () noexcept |
|
Drop the built pipeline (if any) and any cached runner. More... | |
| Run | build_source_internal_ (const RunOptions &opt) |
| PreparedSource | prepare_source_ (RunMode mode, const RunOptions &opt, SinkRequirement sink_req, const char *where) |
|
Shared "build a source-mode pipeline to PAUSED" body for build(RunOptions) and build_cached_source(). More... | |
| void | mark_composition_changed () noexcept |
| std::pair< std::size_t, std::size_t > | append_linear_fragment_ (const Graph &fragment, const char *where) |
| std::pair< std::size_t, std::size_t > | import_composition_fragment_ (const Graph &fragment, const char *where) |
| std::pair< std::size_t, std::size_t > | import_or_reuse_composition_fragment_ (const Graph &fragment, const char *where) |
| bool | is_output_collection_fragment_ (const Graph &fragment) const |
| std::pair< std::size_t, std::size_t > | import_output_collection_fragment_ (const Graph &fragment, const char *where) |
| std::pair< std::size_t, std::size_t > | import_or_reuse_output_collection_fragment_ (const Graph &fragment, const char *where) |
| std::pair< std::size_t, std::size_t > | import_or_reuse_node_fragment_ (std::shared_ptr< Node > node, const char *where) |
| std::pair< std::size_t, std::size_t > | import_or_reuse_model_fragment_ (const Model &model, const char *where) |
| void | connect_imported_ranges_ (std::pair< std::size_t, std::size_t > from_range, std::string_view from_name, std::pair< std::size_t, std::size_t > to_range, std::string_view to_name, const char *where) |
| std::vector< std::shared_ptr< Node > > | linear_nodes_snapshot (const char *where) const |
| void | build_cached_source () |
Private Member Attributes Index
| std::unique_ptr< CompositionGraph > | composition_ |
| std::vector< GroupMeta > | groups_ |
| std::string | last_pipeline_ |
| std::shared_ptr< void > | guard_ |
| std::shared_ptr< void > | verbose_guard_ |
| GraphOptions | opt_ {} |
| std::string | endpoint_name_ |
| TensorCallback | tensor_cb_ |
| uint64_t | graph_id_ = 0 |
| std::atomic< uint64_t > | nodes_version_ {0} |
| std::unique_ptr< BuiltState > | built_ |
| std::unique_ptr< RunCache > | run_cache_ |
| uint64_t | built_version_ = 0 |
| std::shared_ptr< const pipeline_internal::InputRouteProcessor > | input_route_processor_ |
Public Static Functions Index
| static Graph | load (const std::string &path) |
|
Reconstruct a Graph from a previously-saved JSON file. More... | |
Description
The assembly stage — turns a list of Nodes into a runnable, deterministic pipeline.
A Graph does five jobs when you call build():
- Composition — collects Nodes and Graph fragments in the order you added them.
- Validation — runs structural contracts (no empty pipeline, no null nodes, sink last, etc.) and surfaces issues as a structured GraphReport.
- Compilation — translates the Node sequence into a deterministic GStreamer pipeline string with stable element names like n3_videoconvert.
- Negotiation — hands the pipeline to GStreamer, which negotiates caps between adjacent elements (formats, resolutions, framerates, memory layouts).
- Materialization — instantiates the actual GStreamer elements, transitions through NULL → READY → PAUSED state, and returns a Run handle.
Graphs are non-copyable but movable. They are not thread-safe — build a Graph on one thread, then hand the resulting Run to wherever it's needed.
Each Node object can appear at most once in one Graph composition. Composition mutations are atomic: an invalid add/import/connect leaves the Graph unchanged. build() automatically validates final GStreamer element names; calling validate() first is optional.
- See Also
Run for the runtime handle this produces
- See Also
Model — the simplified entry point that wraps a Graph for users who don't need composition flexibility
- See Also
GraphReport for the structured error/diagnostics surface
- See Also
RtspServerHandle for server-mode Graphs
Definition at line 167 of file Graph.h.
Public Member Typedefs
TensorCallback
|
Callback signature used by source-mode pipelines (no input pushed; pipeline produces tensors continuously).
Definition at line 171 of file Graph.h.
Enumerations
CompositionEdgeKind
| strong |
Definition at line 423 of file Graph.h.
SinkRequirement
| strong |
Definition at line 465 of file Graph.h.
Friends
simaai::neat::internal::ModelAccess
|
Definition at line 414 of file Graph.h.
Public Constructors
Graph()
| explicit |
Graph()
| explicit |
Graph()
| delete |
Non-copyable.
Definition at line 183 of file Graph.h.
Graph()
Public Operators
operator=()
| delete |
Non-copyable.
Definition at line 184 of file Graph.h.
operator=()
Public Member Functions
add()
|
Append a single Node to the Graph.
- Parameters
-
node Shared pointer (typically returned by a Node factory like sima::nodes::common::Queue()). Adding the same Node object twice is rejected. Create a distinct object for a distinct vertex.
- Returns
*this to allow chaining.
Definition at line 205 of file Graph.h.
add()
|
add()
|
add()
|
Append a model route as a linear graph fragment.
Definition at line 213 of file Graph.h.
add_output_tensor()
|
Append a tensor-friendly output (auto-inserts convert/scale/caps + sink).
Convenience for "I want my output as a Tensor in a specific format/shape." Equivalent to adding VideoConvert, VideoScale, Caps, and Output Nodes manually but encapsulated.
- Returns
*this to allow chaining.
Definition at line 360 of file Graph.h.
build()
|
Build a long-lived async Run handle, seeding caps from cv::Mat inputs.
- Parameters
-
inputs One Mat per ingress port; used for build-time adaptation.
opt Runtime options (queue depth, overflow policy).
- Exceptions
-
<a href="/reference/cppapi/classes/simaai-neat-neaterror">NeatError</a> on validation or build failure.
build(...) always returns a reusable push/pull runner. Use run(...) for one-shot synchronous execution.
Definition at line 302 of file Graph.h.
build()
|
build()
|
build()
|
Build a Graph as an asynchronous runner without seeding inputs.
Use this for source pipelines (Graphs whose first Node is a producer like RTSPInput or StillImageInput — no push() from user code needed). Push pipelines should prefer build(inputs, ...) so caps can be derived from the actual input. Final launch-name integrity is always checked. Input-dependent connected segments may be materialized later, so their structured build error can surface on the first push() or pull() instead of this call.
Definition at line 396 of file Graph.h.
build()
| inline |
Preserve the established build({}) default-options idiom.
The seeded build(...) overloads also accept an empty braced value, so build({}) is otherwise ambiguous. This exact empty-list compatibility shim forwards to the established RunOptions overload.
Definition at line 404 of file Graph.h.
connect()
|
Connect named endpoints or reusable fragments through the public Graph compiler.
add() means linear splicing. connect() means explicit graph topology. Endpoints are declared with existing nodes::Input("name") / nodes::Output("name") boundary nodes or by model route boundary hints. Graph("name") is only a label/debug name and does not create an endpoint. All overloads lower through the same ExecutionGraphPlan/RunCore path, preserving named endpoints for diagnostics, save/load, visualization, and named Run::push() / Run::pull(). Passing a Node already present in this Graph reuses its vertex, which supports fan-out without duplicating the logical Node.
Definition at line 228 of file Graph.h.
connect()
Definition at line 229 of file Graph.h.
connect()
|
Definition at line 230 of file Graph.h.
connect()
|
Definition at line 231 of file Graph.h.
connect()
|
Definition at line 232 of file Graph.h.
connect()
|
Definition at line 233 of file Graph.h.
connect()
|
Connect one named output pad of a Node to a Graph fragment.
This narrow overload currently supports PCIeSrc request pads named src_N, allowing one physical PCIe source to feed independent decoder branches without exposing a raw GStreamer fragment in the application.
Definition at line 241 of file Graph.h.
connect()
Definition at line 243 of file Graph.h.
connect()
Definition at line 244 of file Graph.h.
connect()
Definition at line 245 of file Graph.h.
connect()
|
Definition at line 246 of file Graph.h.
connect()
|
Definition at line 247 of file Graph.h.
custom()
|
Splice a raw GStreamer launch fragment into the pipeline.
Useful for one-off experiments, third-party plugins NEAT doesn't wrap, or GStreamer features (tee, selector, dynamic pads) that are awkward to model as Nodes. The Give each explicitly named element a unique short name within the final materialized pipeline segment. The build path validates this automatically and rewrites declarations together with named-pad references when a Graph name transform applies. It does not auto-rename collisions.
- Parameters
-
fragment Raw GStreamer launch string (e.g., "identity silent=false ! videocrop ...").
- Returns
*this to allow chaining.
Definition at line 273 of file Graph.h.
custom()
|
Variant that declares the fragment's role (e.g., source vs. sink).
Definition at line 275 of file Graph.h.
describe()
|
Returns a hierarchical, human-readable view of the Nodes added so far.
Definition at line 364 of file Graph.h.
describe_backend()
|
Returns the GStreamer launch string the Graph would emit at build().
Paste into gst-launch-1.0 to reproduce the pipeline outside the framework — invaluable for debugging caps issues or isolating "is this NEAT's bug or GStreamer's?"
- Parameters
-
insert_boundaries If true, inserts diagnostic identity probes between Nodes.
Definition at line 373 of file Graph.h.
inputs()
|
last_pipeline()
| inline |
name()
| noexcept |
outputs()
|
run()
|
Run a source-mode pipeline (no inputs pushed; producer Nodes drive the flow).
Used in conjunction with set_tensor_callback(). The pipeline runs until end-of-stream or until the callback returns false.
- Exceptions
-
<a href="/reference/cppapi/classes/simaai-neat-neaterror">NeatError</a> on validation or runtime failure (with structured GraphReport).
Definition at line 286 of file Graph.h.
run()
|
One-shot synchronous push+pull from cv::Mat inputs.
Definition at line 288 of file Graph.h.
run()
|
run()
|
run_rtsp()
|
Build the Graph and run it as an RTSP server.
The Graph must terminate in an H.264 encoded stream. The returned handle owns a live RTSP server publishing the pipeline's output to network clients. Stop the server by calling handle.stop() or letting the handle go out of scope.
- Parameters
-
opt RTSP server options (mount point, port, RTP port range).
- Returns
Live RtspServerHandle exposing the broadcast URL.
Definition at line 336 of file Graph.h.
save()
|
set_guard()
|
Attach an external lifetime guard (used by externally-managed runtimes).
Definition at line 376 of file Graph.h.
set_name()
|
set_tensor_callback()
|
validate()
|
Validate the Graph against a real input sample without running the pipeline.
Runs structural contracts AND build-time adaptation against the input. Reports whether the pipeline would accept this input shape/format and what conversions would be needed. Useful in CI to catch shape mismatches before deploying.
Definition at line 323 of file Graph.h.
validate()
|
Validate the Graph structurally without running.
Runs all built-in contracts (NonEmptyPipeline, NoNullNodes, SinkLastForRun, etc.) and returns a structured GraphReport. Cheaper than build() because it doesn't instantiate GStreamer state. Useful in unit tests and CI. For a connected Graph, this call validates endpoint topology; each real pipeline segment receives mandatory launch validation when it materializes.
- Returns
GraphReport carrying any contract failures, with error_code and repro_note.
Definition at line 349 of file Graph.h.
Private Member Functions
append_linear_fragment_()
|
Definition at line 524 of file Graph.h.
build_cached_source()
|
Definition at line 551 of file Graph.h.
build_source_internal_()
|
Definition at line 477 of file Graph.h.
connect_imported_ranges_()
|
Definition at line 539 of file Graph.h.
import_composition_fragment_()
|
Definition at line 526 of file Graph.h.
import_or_reuse_composition_fragment_()
|
Definition at line 528 of file Graph.h.
import_or_reuse_model_fragment_()
|
Definition at line 537 of file Graph.h.
import_or_reuse_node_fragment_()
|
Definition at line 535 of file Graph.h.
import_or_reuse_output_collection_fragment_()
|
Definition at line 534 of file Graph.h.
import_output_collection_fragment_()
|
Definition at line 531 of file Graph.h.
invalidate_built_()
| noexcept |
Drop the built pipeline (if any) and any cached runner.
Tears down GStreamer resources via RAII; safe to call when there is no built state. Never throws.
Definition at line 476 of file Graph.h.
is_output_collection_fragment_()
|
Definition at line 530 of file Graph.h.
linear_nodes_snapshot()
|
Definition at line 550 of file Graph.h.
mark_composition_changed()
| noexcept |
Definition at line 523 of file Graph.h.
prepare_source_()
|
Shared "build a source-mode pipeline to PAUSED" body for build(RunOptions) and build_cached_source().
Validates, materializes, compiles, attaches all probes, resolves the sink, and drives to GST_STATE_PAUSED. Callers add the state transition step (PLAYING for live build, or stay at PAUSED to cache).
Definition at line 483 of file Graph.h.
Private Member Attributes
built_
|
Definition at line 518 of file Graph.h.
built_version_
|
Definition at line 520 of file Graph.h.
composition_
|
Definition at line 508 of file Graph.h.
endpoint_name_
|
Definition at line 514 of file Graph.h.
graph_id_
|
Definition at line 516 of file Graph.h.
groups_
|
Definition at line 509 of file Graph.h.
guard_
|
Definition at line 511 of file Graph.h.
input_route_processor_
|
Definition at line 521 of file Graph.h.
last_pipeline_
|
Definition at line 510 of file Graph.h.
nodes_version_
|
Definition at line 517 of file Graph.h.
opt_
|
Definition at line 513 of file Graph.h.
run_cache_
|
Definition at line 519 of file Graph.h.
tensor_cb_
|
Definition at line 515 of file Graph.h.
verbose_guard_
|
Definition at line 512 of file Graph.h.
The documentation for this class was generated from the following file:
Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.