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, RunMode mode=RunMode::Async, const RunOptions &opt={}) |
|
Build a long-lived Run handle, seeding caps from cv::Mat inputs. More... | |
| Run | build (const TensorList &inputs, RunMode mode=RunMode::Async, const RunOptions &opt={}) |
| Run | build (const Sample &inputs, RunMode mode=RunMode::Async, 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 |
SinkRequirement
Friends
simaai::neat::internal::ModelAccess
|
Definition at line 367 of file Graph.h.
Public Constructors
Graph()
| explicit |
Graph()
| explicit |
Graph()
| delete |
Graph()
Public Operators
operator=()
| delete |
operator=()
Public Member Functions
add()
|
add()
|
add()
|
add()
|
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.
build()
|
Build a long-lived Run handle, seeding caps from cv::Mat inputs.
- Parameters
-
inputs One Mat per ingress port; used for build-time adaptation.
mode Async (default; pipeline runs continuously) or Sync.
opt Runtime options (queue depth, overflow policy).
- Exceptions
-
<a href="/reference/cppapi/classes/simaai-neat-neaterror">NeatError</a> on validation or build failure.
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.
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().
connect()
connect()
|
connect()
|
connect()
|
connect()
connect()
connect()
connect()
|
connect()
|
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.
custom()
|
describe()
|
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.
inputs()
|
last_pipeline()
| inline |
Returns the GStreamer launch string from the most recent build() call.
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).
run()
|
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.
save()
|
set_guard()
|
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.
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.
Private Member Functions
append_linear_fragment_()
|
build_cached_source()
connect_imported_ranges_()
|
import_composition_fragment_()
|
import_or_reuse_composition_fragment_()
|
import_or_reuse_model_fragment_()
|
import_or_reuse_node_fragment_()
|
import_or_reuse_output_collection_fragment_()
|
import_output_collection_fragment_()
|
invalidate_built_()
| noexcept |
is_output_collection_fragment_()
|
linear_nodes_snapshot()
|
mark_composition_changed()
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).
Private Member Attributes
built_
|
built_version_
|
composition_
|
endpoint_name_
|
graph_id_
|
groups_
|
guard_
|
input_route_processor_
|
last_pipeline_
|
nodes_version_
|
opt_
|
run_cache_
|
tensor_cb_
|
Definition at line 464 of file Graph.h.
verbose_guard_
The documentation for this class was generated from the following file:
Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.