Graph.h File

Graph — the assembly stage that takes Nodes and turns them into a runnable Run. More...

Included Headers

#include "builder/Node.h" #include "pipeline/GraphOptions.h" #include "pipeline/Run.h" #include "builder/GraphPrinter.h" #include "nodes/common/Output.h" #include "nodes/common/Caps.h" #include "nodes/common/FileInput.h" #include "nodes/common/JpegDecode.h" #include "nodes/common/VideoTrackSelect.h" #include "nodes/common/Queue.h" #include "nodes/common/VideoConvert.h" #include "nodes/common/VideoScale.h" #include "nodes/io/StillImageInput.h" #include "nodes/io/Input.h" #include "nodes/io/RTSPInput.h" #include "nodes/rtp/H264Depacketize.h" #include "nodes/sima/H264DecodeSima.h" #include "nodes/sima/H264EncodeSima.h" #include "nodes/sima/H264Parse.h" #include "nodes/sima/H264Packetize.h" #include <atomic> #include <cstdint> #include <functional> #include <memory> #include <optional> #include <span> #include <string> #include <string_view> #include <utility> #include <vector> #include <opencv2/core/mat.hpp> #include <gst/gst.h>

Namespaces Index

namespace	simaai
namespace	neat
namespace	internal
namespace	graph
namespace	pipeline_internal

Classes Index

class	RtspServerHandle
	Live handle for a Graph running in RTSP server mode. More...
class	Graph
	The assembly stage — turns a list of Nodes into a runnable, deterministic pipeline. More...
struct	EndpointEdgeMeta
struct	CompositionEdge
struct	GroupMeta
	Per-fragment metadata captured during build. More...
struct	NamedFragment

Description

Graph — the assembly stage that takes Nodes and turns them into a runnable Run.

Graph is the central concept of the framework. It collects Nodes and reusable Graph fragments, validates them against built-in contracts, compiles them into a deterministic GStreamer pipeline string, instantiates the pipeline, negotiates caps between adjacent elements, and returns a Run handle for push/pull execution. Model is internally a Graph wrapper: the same composition, validation, and runtime machinery powers Model underneath. New users typically use Model::run(); advanced users compose their own Graphs with graph.add(model) plus extra Nodes for input sources, custom processing, side branches, or RTSP server output.

See Also

Run for the runtime handle a built Graph produces

See Also

RtspServerHandle for server-mode Graphs

See Also

"Graphs: the assembly contract" (§0.12 of the design deep dive)

File Listing

The file content with the documentation metadata removed is:

1

19#pragma once

20

21#include "builder/Node.h"

22#include "pipeline/GraphOptions.h"

23#include "pipeline/Run.h"

24#include "builder/GraphPrinter.h"

25#include "nodes/common/Output.h"

26#include "nodes/common/Caps.h"

27#include "nodes/common/FileInput.h"

28#include "nodes/common/JpegDecode.h"

29#include "nodes/common/VideoTrackSelect.h"

30#include "nodes/common/Queue.h"

31#include "nodes/common/VideoConvert.h"

32#include "nodes/common/VideoScale.h"

33#include "nodes/io/StillImageInput.h"

34#include "nodes/io/Input.h"

35#include "nodes/io/RTSPInput.h"

36#include "nodes/rtp/H264Depacketize.h"

37#include "nodes/sima/H264DecodeSima.h"

38#include "nodes/sima/H264EncodeSima.h"

39#include "nodes/sima/H264Parse.h"

40#include "nodes/sima/H264Packetize.h"

41

42#include <atomic>

43#include <cstdint>

44#include <functional>

45#include <memory>

46#include <optional>

47#include <span>

48#include <string>

49#include <string_view>

50#include <utility>

51#include <vector>

52

53#include <opencv2/core/mat.hpp>

54#include <gst/gst.h>

55

56namespace simaai::neat {

57namespace internal {

58struct ModelAccess;

59}

60namespace graph {

61class Node;

62}

63namespace pipeline_internal {

64struct InputRouteProcessor;

65}

66

67class Graph;

68class Model;

69

70#ifdef SIMA_NEAT_INTERNAL

71namespace runtime {

72struct ExecutionGraphPlan;

73struct FragmentBoundaryHints;

74struct FragmentPlan;

75struct Provenance;

76ExecutionGraphPlan compile_public_graph(const Graph& graph, const RunOptions& opt,

77 std::optional<Sample> seed);

78} // namespace runtime

79#endif

80

94class RtspServerHandle {

95public:

97 RtspServerHandle() = default;

99 ~RtspServerHandle();

100

101 RtspServerHandle(const RtspServerHandle&) = delete;

102 RtspServerHandle& operator=(const RtspServerHandle&) = delete;

103

104 RtspServerHandle(RtspServerHandle&&) noexcept;

105 RtspServerHandle& operator=(RtspServerHandle&&) noexcept;

106

108 const std::string& url() const {

109 return url_;

110 }

112 void stop();

114 void kill() {

115 stop();

116 }

118 bool running() const;

119

120private:

121 friend class Graph;

122

123 std::string url_;

124 void* impl_ = nullptr;

125 std::shared_ptr<void> guard_;

126};

127

160class Graph {

161public:

164 using TensorCallback = std::function<bool(const simaai::neat::Tensor&)>;

165

167 explicit Graph(const GraphOptions& opt = {});

171 explicit Graph(std::string name, const GraphOptions& opt = {});

175 ~Graph() noexcept;

176 Graph(const Graph&) = delete;

177 Graph& operator=(const Graph&) = delete;

178 Graph(Graph&&) noexcept;

179 Graph& operator=(Graph&&) noexcept;

180

182 Graph& set_name(std::string name);

184 const std::string& name() const noexcept;

186 std::vector<std::string> inputs() const;

188 std::vector<std::string> outputs() const;

189

190 // ── Core: add Nodes / Graph fragments ───────────────────────────────────────────────────

197 Graph& add(std::shared_ptr<Node> node);

200 Graph& add(const Graph& fragment);

203 Graph& add(Graph&& fragment);

205 Graph& add(const Model& model);

206

207 // ── Explicit graph composition ───────────────────────────────────────────────────────────

218 Graph& connect(std::string_view from_endpoint, std::string_view to_endpoint);

219 Graph& connect(const Graph& from, const Graph& to);

220 Graph& connect(std::shared_ptr<Node> from, std::shared_ptr<Node> to);

221 Graph& connect(const Graph& from, std::shared_ptr<Node> to);

222 Graph& connect(std::shared_ptr<Node> from, const Graph& to);

223 Graph& connect(const Model& from, const Model& to);

224 Graph& connect(const Model& from, const Graph& to);

225 Graph& connect(const Graph& from, const Model& to);

226 Graph& connect(const Model& from, std::shared_ptr<Node> to);

227 Graph& connect(std::shared_ptr<Node> from, const Model& to);

228

229#ifdef SIMA_NEAT_INTERNAL

231 std::size_t append_pipeline_vertex_for_internal_graph_(std::shared_ptr<Node> node);

233 std::size_t

234 append_runtime_vertex_for_internal_graph_(std::shared_ptr<simaai::neat::graph::Node> node);

236 void connect_runtime_port_for_internal_graph_(std::size_t from, std::string_view from_port,

237 std::size_t to, std::string_view to_port);

238#endif

239

240 // ── Custom GStreamer escape hatch ────────────────────────────────────────────────────────

251 Graph& custom(std::string fragment);

253 Graph& custom(std::string fragment, InputRole role);

254

255 // ── Typed runner: last node must be Output() ────────────────────────────────────────────

264 void run();

266 TensorList run(const std::vector<cv::Mat>& inputs, const RunOptions& opt = {});

268 TensorList run(const TensorList& inputs, const RunOptions& opt = {});

270 Sample run(const Sample& inputs, const RunOptions& opt = {});

278 Run build(const std::vector<cv::Mat>& inputs, RunMode mode = RunMode::Async,

279 const RunOptions& opt = {});

281 Run build(const TensorList& inputs, RunMode mode = RunMode::Async, const RunOptions& opt = {});

283 Run build(const Sample& inputs, RunMode mode = RunMode::Async, const RunOptions& opt = {});

291 GraphReport validate(const ValidateOptions& opt, const cv::Mat& input) const;

292

293 // ── Server-style run ────────────────────────────────────────────────────────────────────

304 RtspServerHandle run_rtsp(const RtspServerOptions& opt);

305

315 GraphReport validate(const ValidateOptions& opt = {}) const;

316

317 // ── Tensor-friendly output helper ────────────────────────────────────────────────────────

326 Graph& add_output_tensor(const OutputTensorOptions& opt = {});

327

328 // ── UX helpers ───────────────────────────────────────────────────────────────────────────

330 std::string describe(const GraphPrinter::Options& opt = {}) const;

339 std::string describe_backend(bool insert_boundaries = false) const;

340

342 void set_guard(std::shared_ptr<void> guard);

343

345 void set_tensor_callback(TensorCallback cb);

346

348 void save(const std::string& path) const;

350 static Graph load(const std::string& path);

351

359 Run build(const RunOptions& opt = {});

360

362 const std::string& last_pipeline() const {

363 return last_pipeline_;

364 }

365

366private:

367 friend struct simaai::neat::internal::ModelAccess;

368

369 // Opaque internal state types — the GStreamer pipeline + sink are owned via RAII

370 // handles defined in the private pipeline build implementation, so the public header never

371 // needs to know how they are torn down. Forward-declared here; defined alongside `RunCache` and

372 // `CompositionGraph` in the internal detail header.

373 struct BuiltState;

374 struct CompositionGraph;

375 enum class CompositionEdgeKind {

376 ImplicitLinear,

377 RuntimePort,

378 PublicEndpoint,

379 };

380 struct EndpointEdgeMeta {

381 std::string from_endpoint;

382 std::string to_endpoint;

383 };

384 struct CompositionEdge {

385 std::size_t from = static_cast<std::size_t>(-1);

386 std::size_t to = static_cast<std::size_t>(-1);

387 CompositionEdgeKind kind = CompositionEdgeKind::ImplicitLinear;

388 std::string from_port;

389 std::string to_port;

390 std::optional<EndpointEdgeMeta> endpoint;

391 };

392 struct GroupMeta;

393 struct NamedFragment;

394 struct RunCache;

395#ifdef SIMA_NEAT_INTERNAL

396 struct CompositionView {

397 std::vector<std::shared_ptr<Node>> linear_nodes;

398 std::vector<std::shared_ptr<Node>> vertices;

399 std::vector<std::shared_ptr<simaai::neat::graph::Node>> runtime_vertices;

400 std::span<const CompositionEdge> edges;

401 std::span<const GroupMeta> groups;

402 std::span<const runtime::FragmentPlan> fragments;

403 std::span<const NamedFragment> named_fragments;

404 GraphOptions options;

405 std::string graph_name;

406 bool graph_user_named = false;

407 std::uint64_t graph_id = 0;

408 std::uint64_t graph_version = 0;

409 bool linear = true;

410 };

411#endif

412

413 // Source-mode build helper. Body defined in the private pipeline build implementation.

414 struct PreparedSource;

415 enum class SinkRequirement : int { Required, OptionalIfPresent };

416

417#ifdef SIMA_NEAT_INTERNAL

418 CompositionView composition_view_for_internal_compile() const;

419 friend runtime::ExecutionGraphPlan runtime::compile_public_graph(const Graph& graph,

420 const RunOptions& opt,

421 std::optional<Sample> seed);

422#endif

423

426 void invalidate_built_() noexcept;

427

432 PreparedSource prepare_source_(RunMode mode, const RunOptions& opt, SinkRequirement sink_req,

433 const char* where);

443 struct GroupMeta {

444 std::size_t start = 0;

445 std::size_t end = 0;

446 NodeCapsBehavior caps_behavior = NodeCapsBehavior::Dynamic;

447 std::string label;

448 };

449

450 struct NamedFragment {

451 std::size_t start = 0;

452 std::size_t end = 0;

453 std::string name;

454 bool user_named = false;

455 };

456

457 std::unique_ptr<CompositionGraph> composition_;

458 std::vector<GroupMeta> groups_;

459 std::string last_pipeline_;

460 std::shared_ptr<void> guard_;

461 std::shared_ptr<void> verbose_guard_;

462 GraphOptions opt_{};

463 std::string endpoint_name_;

464 TensorCallback tensor_cb_;

465 uint64_t graph_id_ = 0;

466 std::atomic<uint64_t> nodes_version_{0};

467 std::unique_ptr<BuiltState> built_;

468 std::unique_ptr<RunCache> run_cache_;

469 uint64_t built_version_ = 0;

470 std::shared_ptr<const pipeline_internal::InputRouteProcessor> input_route_processor_;

471

472 void mark_composition_changed();

473 std::pair<std::size_t, std::size_t> append_linear_fragment_(const Graph& fragment,

474 const char* where);

475 std::pair<std::size_t, std::size_t> import_composition_fragment_(const Graph& fragment,

476 const char* where);

477 std::pair<std::size_t, std::size_t> import_or_reuse_composition_fragment_(const Graph& fragment,

478 const char* where);

479 bool is_output_collection_fragment_(const Graph& fragment) const;

480 std::pair<std::size_t, std::size_t> import_output_collection_fragment_(const Graph& fragment,

481 const char* where);

482 std::pair<std::size_t, std::size_t>

483 import_or_reuse_output_collection_fragment_(const Graph& fragment, const char* where);

484 std::pair<std::size_t, std::size_t> import_or_reuse_node_fragment_(std::shared_ptr<Node> node,

485 const char* where);

486 std::pair<std::size_t, std::size_t> import_or_reuse_model_fragment_(const Model& model,

487 const char* where);

488 void connect_imported_ranges_(std::pair<std::size_t, std::size_t> from_range,

489 std::string_view from_name,

490 std::pair<std::size_t, std::size_t> to_range,

491 std::string_view to_name, const char* where);

492#ifdef SIMA_NEAT_INTERNAL

493 void attach_fragment_boundary_hints_(std::size_t start, std::size_t end,

494 runtime::FragmentBoundaryHints hints);

495 void attach_fragment_boundary_hints_(std::size_t start, std::size_t end,

496 runtime::FragmentBoundaryHints hints,

497 runtime::Provenance provenance);

498#endif

499 std::vector<std::shared_ptr<Node>> linear_nodes_snapshot(const char* where) const;

500 void build_cached_source();

501};

502

503} // namespace simaai::neat

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.