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 (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 (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... | |
| 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... | |
| 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 () |
| 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.
- 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 160 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 164 of file Graph.h.
Enumerations
CompositionEdgeKind
| strong |
Definition at line 385 of file Graph.h.
SinkRequirement
| strong |
Definition at line 425 of file Graph.h.
Friends
simaai::neat::internal::ModelAccess
|
Definition at line 377 of file Graph.h.
Public Constructors
Graph()
| explicit |
Graph()
| explicit |
Graph()
| delete |
Non-copyable.
Definition at line 176 of file Graph.h.
Graph()
Public Operators
operator=()
| delete |
Non-copyable.
Definition at line 177 of file Graph.h.
operator=()
Public Member Functions
add()
|
add()
|
add()
|
add()
|
Append a model route as a linear graph fragment.
Definition at line 205 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 336 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 280 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.
Definition at line 369 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().
Definition at line 218 of file Graph.h.
connect()
Definition at line 219 of file Graph.h.
connect()
|
Definition at line 220 of file Graph.h.
connect()
|
Definition at line 221 of file Graph.h.
connect()
|
Definition at line 222 of file Graph.h.
connect()
Definition at line 223 of file Graph.h.
connect()
Definition at line 224 of file Graph.h.
connect()
Definition at line 225 of file Graph.h.
connect()
|
Definition at line 226 of file Graph.h.
connect()
|
Definition at line 227 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 trade-off: you lose deterministic naming for the spliced fragment. Use sparingly.
- Parameters
-
fragment Raw GStreamer launch string (e.g., "identity silent=false ! videocrop ...").
- Returns
*this to allow chaining.
Definition at line 251 of file Graph.h.
custom()
|
Variant that declares the fragment's role (e.g., source vs. sink).
Definition at line 253 of file Graph.h.
describe()
|
Returns a hierarchical, human-readable view of the Nodes added so far.
Definition at line 340 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 349 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 264 of file Graph.h.
run()
|
One-shot synchronous push+pull from cv::Mat inputs.
Definition at line 266 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 314 of file Graph.h.
save()
|
set_guard()
|
Attach an external lifetime guard (used by externally-managed runtimes).
Definition at line 352 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 301 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.
- Returns
GraphReport carrying any contract failures, with error_code and repro_note.
Definition at line 325 of file Graph.h.
Private Member Functions
append_linear_fragment_()
|
Definition at line 483 of file Graph.h.
build_cached_source()
|
Definition at line 510 of file Graph.h.
connect_imported_ranges_()
|
Definition at line 498 of file Graph.h.
import_composition_fragment_()
|
Definition at line 485 of file Graph.h.
import_or_reuse_composition_fragment_()
|
Definition at line 487 of file Graph.h.
import_or_reuse_model_fragment_()
|
Definition at line 496 of file Graph.h.
import_or_reuse_node_fragment_()
|
Definition at line 494 of file Graph.h.
import_or_reuse_output_collection_fragment_()
|
Definition at line 493 of file Graph.h.
import_output_collection_fragment_()
|
Definition at line 490 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 436 of file Graph.h.
is_output_collection_fragment_()
|
Definition at line 489 of file Graph.h.
linear_nodes_snapshot()
|
Definition at line 509 of file Graph.h.
mark_composition_changed()
|
Definition at line 482 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 442 of file Graph.h.
Private Member Attributes
built_
|
Definition at line 477 of file Graph.h.
built_version_
|
Definition at line 479 of file Graph.h.
composition_
|
Definition at line 467 of file Graph.h.
endpoint_name_
|
Definition at line 473 of file Graph.h.
graph_id_
|
Definition at line 475 of file Graph.h.
groups_
|
Definition at line 468 of file Graph.h.
guard_
|
Definition at line 470 of file Graph.h.
input_route_processor_
|
Definition at line 480 of file Graph.h.
last_pipeline_
|
Definition at line 469 of file Graph.h.
nodes_version_
|
Definition at line 476 of file Graph.h.
opt_
|
Definition at line 472 of file Graph.h.
run_cache_
|
Definition at line 478 of file Graph.h.
tensor_cb_
|
Definition at line 474 of file Graph.h.
verbose_guard_
|
Definition at line 471 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.