Marc Schier
cef83550cb
# Description Implements **OPC UA — Vision** and uses it to build the demo the companion specifications were drafted for: an eye-in-hand camera watches a bin of parts, a language model *looks at the frame*, decides which part matches the instruction, and commands the robot through Robot Intent — with the OpenUSD viewer showing the arm move and the bin empty out. > **Draft, and stacked.** [#4195](https://github.com/OPCFoundation/UA-.NETStandard/pull/4195) has merged and master is merged in, so what is left on top of `master` is the Vision work plus the unmerged `marcschier/ai-model-management` branch, which the demo needs for the model/dataset/deployment provenance. Review the Vision commits; the AI Model Management work lands with its own PR. ## What is here **The specification, implemented.** `Opc.Ua.Vision` is generated from the spec's own `Opc.Ua.Vision.NodeSet2.xml`, vendored byte-identically (SHA-256 `79C592C6…`, verified against a fresh download and stored LF-preserved like the Robot Intent NodeSet). `Opc.Ua.Vision.Server` builds the §4.2 discovery object, sensors, the coordinate-frame tree, calibrations, media endpoints, inference pipelines and the §9 feedback methods, with rendering and inference behind injectable providers. `Opc.Ua.Vision.Client` is built on the generated ObjectType proxies and composes transforms across the frame tree, which is what turns a detection in camera coordinates into a pose a robot can act on. **Two perception paths behind one contract**, which is exactly what `InferenceLocationEnum` is for. `OnServer` is a deterministic detector derived from the stage's ground truth — no model, no network, no GPU, so CI can exercise the whole loop. `EdgeOffServer` is the agent: it sees the frame over MCP and calls `SubmitDetections`, and the Server publishes results it did not compute. A client reads `DetectionResultType` identically either way. **The agent's eyes.** `tools/Opc.Ua.Mcp.Vision` adds 22 `vision_*` tools, which with the four shared connection tools makes the `vision` profile 26; `vision_get_frame` returns the camera image as an MCP `ImageContentBlock`, so the model looks at pixels rather than reading a description of them. Tool profiles now compose — `--profile vision,robotics` yields 62 tools — so one agent can both see and act without dragging in the full 136-tool catalogue. **The cell.** `samples/Robotics/BinPickingCell` follows the spec's own Robotics-Vision Addendum: the `world → robot_base → flange → gripper_tcp` frame tree with `camera_eih` on the flange, the `HandEye` extrinsics and the `Intrinsics612x512` intrinsics — the addendum's 2448×2048 calibration scaled to the 4×4-binned grid the camera actually delivers. `samples/Robotics/BinPickingClient` hosts the composed MCP catalogue and optionally the viewer. **Documentation.** `docs/Vision.md` (~800 lines) covers the model, hosting, the build context, every topology builder, both perception paths, feedback, the MCP profile and the limitations; linked from `docs/README.md`, with the profile table in `docs/McpServer.md` and READMEs for both samples. ## Evidence, not assertions Each of these was measured on a running system rather than assumed: | Claim | Evidence | |---|---| | The camera sees the bin | 612×512 frame with the bin and all five parts in view — red `(212,47,47)`, green `(61,193,71)`, blue `(54,85,218)`, yellow `(215,196,58)`, orange `(209,119,55)` | | An agent can act on what it sees | Over MCP, `vision_get_frame` returns a 612×512 PNG that decodes from base64 to 1,254,051 bytes, the descriptor beside the detections says 612×512, and all five `BoundingBox2D` centres land **inside** the frame on the pixel colour their own detection claims | | The geometry is right | A detection composed `camera_eih → world` lands on the authored position, residual **0.0000 m** — on both the on-server and off-server paths | | The detector tracks the world | Placing a part drops the next scan from 5 detections to 4, with that part absent | | The robot obeys the agent | Scripted run took command authority and completed a pick and a place, both `Succeeded` | | Tool catalogues are honest | Counted from a running server: vision 26, robotics 40, `vision,robotics` 62, full 136, **zero duplicates** | | Every node is browsable by NodeId | Eight representative NodeIds — both folders, a pipeline, a frame, the sensor, its Calibrations folder, the HandEye calibration, the Media folder — all `Good` | That tool-count check matters because the profile tests collapse names into a `HashSet` and *cannot see* a duplicate registration — so the new tests count registrations, not names. ## Things that were wrong, and are not now Writing the tests found three defects of one kind — code that answered instead of refusing. A zero-norm quaternion was silently rewritten to identity, so a caller with an all-zero orientation got a confident wrong grasp pose. `SubmitCorrection` rewrote a null `ResultId` to empty and called the sink anyway. A bad `StageIdentifier` **killed the host process** inside native `UsdStage.Open`, via an exception .NET cannot catch. All three now refuse loudly and are pinned by tests. **Nodes that existed but could not be reached.** The node manager indexes the Vision root before configurators run, so everything the fluent builder grafted on afterwards — both folders, the pipelines with their Results and Feedback, the frames, the sensors with their optics, calibrations and media endpoints — was never added to the index. Browsing *forward from a parent* worked, because that walks `NodeState.Children` in memory; browsing any of those nodes *by its own NodeId* returned `BadNodeIdUnknown`, which is how an ordinary client and the MCP discovery tools navigate. Registration is now deferred and flushed after each configurator. The first fix covered only the DI path and left the documented non-DI fallback broken in exactly the same way, so `ConfigureVisionAsync` now exists and registers what it builds. That defect survived a green suite because every test browsed children. The new tests assert by NodeId, and were checked against the broken code — with the flush removed, they fail. **Every Method was uncallable.** The Server passed 426 unit tests while not one of its Methods could be invoked over a real session — `RunInference` returned `Bad_TooManyArguments`, and so did every other Method that takes arguments, which is all of them but `StartContinuous` and `Stop`. Three independent faults, each sufficient on its own: the Method nodes were never created (they are Optional children, and the dispatcher guards every attachment with a null check, so it silently attached nothing); nothing declared the arguments, so the stack concluded none were expected; and `MethodDeclarationId` pointed at a synthesised NodeId rather than the NodeSet declaration a client calls with, so the lookup missed the instance Method entirely. The builder now creates the Methods, the `Results` folder and the `Feedback` object when a provider or sink is configured, declares every signature, and names the right declaration. Unit tests could not have caught this: they invoke the handler delegates directly and never go through `MethodState.Call`. It took an end-to-end test over a real session. Relatedly, children created by the generated `CreateOrReplace` helpers carry no `ReferenceTypeId`, so nothing could reach them — fixed once in the build context rather than at the several dozen call sites. **And one where I was wrong.** Earlier in this branch I reversed my own agents' decision and made `SubmitDetections` accept an empty detection set, reasoning that "I looked and the bin is empty" is a correct observation and refusing it forces a correct agent to invent a detection. The reasoning is sound; it is also an argument *against* the specification rather than an implementation of it. §9.5 is normative and explicit — its StatusCode table lists `Bad_InvalidArgument` for "`Detections` empty; or `SubmitCorrection` supplies both or neither corrected array". Worse, **none of §9.5's argument rules were enforced anywhere** — the dispatcher forwarded every submission straight to the feedback sink, so conformance depended on whichever sink a host installed. They are Server obligations, so they now live in the dispatcher, ahead of the sink, proven by strict mocks that would throw if the sink were consulted. The usability problem is real and does not go away by conforming, so it is raised where it can be fixed: [opcua-drafts#70](https://github.com/marcschier/opcua-drafts/issues/70). ## Tracking the updated drafts The Vision, Robot Intent and AI Model Management NodeSets on `opcua-drafts` `main` have moved, partly because of feedback this branch raised. All three are re-vendored byte-identically — verified by comparing git blob hashes against the upstream files rather than by eye — and the implementations follow. **Two statements that were previously inexpressible now have a wire representation.** `SubmitDetections` takes `SceneIsEmpty` and `SubmitCorrection` takes `RetractAll`, so an agent can report "I examined this frame and there is nothing in it" — the terminating condition of the bin-picking task — and can retract a false positive by correcting a result down to nothing. Both are checked in both directions, because the flag is exactly what separates a deliberate empty observation from a lost payload: an empty array without the flag is refused, and the flag with an array attached is refused as two contradictory claims about one frame. Implemented in the dispatcher, the client, the MCP tools the agent drives, and the sample cell. Also absorbed: `LampType` and `LightingMode` became enums (§66), `ProfileName` became `DefaultProfileName` on the endpoint (distinct from the `ProfileName` a caller passes to `GetStreamEndpoint`, which keeps its name), AI `Invoke`/`InvokeAsync` gained `PayloadUri` under the same exactly-one rule, and AI `ListModels` gained a `ContinuationPoint` — because `MaxResults` alone puts everything past the bound permanently out of reach. **OpenUSD is on `0.9.0-alpha`**, verified on the running cell rather than by restore alone: D3D12 backend, 612×512 frame, the bin and all five parts in view and detected — the same result `0.8.0-alpha` produced. The one local workaround that survives is `VisionMethodArguments`, and its reason has changed rather than gone away: the builder materialises these Methods as Optional children through `CreateOrReplace`, which constructs the state object directly and never runs the generated factory that now carries the signatures. Checked rather than assumed — removing the declarations fails five of the eight `VisionMethodSurfaceTests`. ## Review feedback Three threads, all addressed in `0fe2803a3`: - **The AI Model Management work is now a library family, not a sample.** `src/Opc.Ua.AI` (model), `.Inference` (`IInferenceBackend` and backends), `.Server` (node manager) and `.Client` (discovery, reads, calls, artefact transfer), in the same shape as the Robotics and Vision families; the samples become `samples/AI/ModelManagementServer` and `ModelManagementClient`. The client library needed real work rather than relocation: its browsing surface was `private` inside the sample's scenario runner, so moving the file alone would have produced a library nobody could call. - **No cloud-vendor SDK is referenced anywhere.** Inference goes through `Microsoft.Extensions.AI` — an `IChatClient` is implemented by hosted services and on-device runtimes alike, which is exactly the property clause 8.1 asserts. `Azure.Identity` is gone: workload identity is not an Azure feature, every platform projects a token into a file and each SDK reads that file behind its own API, so the resolver reads it directly. The comment claiming `Microsoft.Extensions.AI` would force a `System.Text.Json` bump was stale — it pins 10.0.10, which this repository already centralises on. - **`BinPickingCell` and `BinPickingClient` moved into `samples/Robotics/`**, which is where they belonged: the cell was already linking the arm, its kinematics and both USD assets out of `IntentEnabledRobot`. ## Upstream Work that belonged elsewhere went elsewhere rather than being worked around locally: - **`openusd-dotnet` [#13](https://github.com/marcschier/openusd-dotnet/pull/13)** — merged and shipped in `0.8.0-alpha`. `SilkFrameCapture.Capture` rendered only the first capture of a session and silently returned a blank frame for every one after it. Also filed [#14](https://github.com/marcschier/openusd-dotnet/issues/14) (no camera-by-prim API) and [#15](https://github.com/marcschier/openusd-dotnet/issues/15) (skipped tests reported as passed — which fooled me for several runs). Both are fixed; this branch takes `0.8.0-alpha` and deletes two workarounds, including 143 lines of hand-rolled projection maths. - **`opcua-drafts` [#66](https://github.com/marcschier/opcua-drafts/issues/66)–[#69](https://github.com/marcschier/opcua-drafts/issues/69)** — a close read of the spec produced 22 candidate ambiguities; 12 were discarded as misreadings with clause citations and the remaining 10 filed. One is concrete: five members exist in the NodeId CSV that no clause documents. - **`opcua-drafts` [#70](https://github.com/marcschier/opcua-drafts/issues/70)** — §9.5 could not express an empty observation or a false-positive retraction. **Adopted**, with the explicit-flag resolution argued for: `SubmitDetections` gained `SceneIsEmpty`, `SubmitCorrection` gained `RetractAll`, and the corrected-array rule relaxed from *exactly one* to *at most one*. - **`opcua-drafts` [#71](https://github.com/marcschier/opcua-drafts/issues/71)** — the Vision NodeSet browse-named all 13 `InputArguments` / `OutputArguments` Properties in the Vision namespace rather than the base namespace, so a stack could not find them and every Method in the specification was uncallable. **Fixed**; this branch now tracks the corrected artefact. ## The defect underneath it all The end-to-end suite was removed earlier in this branch because nine of its fourteen tests failed on one symptom: a client could not open a pipeline's `Feedback` object or enumerate its `Results`, even though browsing the same parent listed both. Restoring it meant explaining that, and the explanation was not in Vision. `RelativePathElement` initialised **`IsInverse` to `true`**. A caller that sets a `ReferenceTypeId` and a `TargetName` — which reads as *"the child reached by this Reference"* — was therefore asking the Server for the **inverse** Reference, and got `Bad_NoMatch` with nothing in the request to suggest why. `ObjectTypeClient.ResolveChildNodeIdAsync` is such a caller, and it is what **every source-generated Optional-child accessor in the stack** is built on — the accessor whose own documentation cites `AlarmConditionTypeClient.GetShelvingStateAsync` as an example. Vision is merely where it surfaced, because Vision puts two Optional children on the path an off-Server agent must take. The sibling helper in `StateMachineTypeClientExtensions` already set `IsInverse = false` by hand, which is the shape of a trap rather than a default. The default is now forward, `ResolveChildNodeIdAsync` says so explicitly, and the existing test that had recorded `true` as *expected* now pins `false` with the reasoning. Of the forty `RelativePathElement` construction sites in the tree, that accessor was **the only one relying on the default at all** — every deliberate caller already set it. Two further defects were found underneath it, both real and both fixed: - The generated `CreateOrReplace` helpers construct a child state object directly and leave **`TypeDefinitionId`** unset as well as `ReferenceTypeId`. A child referenced by nothing cannot be browsed; one with no type definition is a malformed Object that a client filtering by type silently skips — which is exactly what `EnumerateResultsAsync` does. Normalisation moved to `VisionNodeManager`, so it also covers the case the builder cannot see: a result published **at runtime** by an inference provider, long after the address space was built. That path produced results a client could list but not read. - `Opc.Ua.AI` shipped without an `AssemblyInfo`, so the solution built with six `CA1014` warnings. I had initially "fixed" this in the Vision client with Browse-based fallbacks, on the strength of a probe that appeared to show `TranslateBrowsePathsToNodeIds` failing even for `Server → ServerStatus`. That probe was wrong: it used an unqualified `ReferenceTypeIds`, which inside a `Opc.Ua.Vision.*` namespace binds to *Vision's* `ReferenceTypeIds` and yields a nonsense NodeId. Chasing that to the end is what turned up the real cause. **The fallbacks are gone** — they would have hidden a stack-wide bug behind a Vision-shaped workaround, and one of them matched on browse name while ignoring the namespace index. `tests/Opc.Ua.Vision.Intent.Tests` is restored and back in `UA.slnx`, passing **14/14** on its own merit rather than through a client-side workaround. A registration test now pins the pipeline's `Feedback` and `Results` children, which nothing covered before. ## Running it, and what that found The demo's premise is that a language model **looks at the bin and reasons about what it sees**. Running it end to end showed it could not, for reasons no test covered, because every one of them lived between components. **The sample did not compile.** Two `CS8604` nullable errors with `TreatWarningsAsErrors`, so neither the cell server nor the demo could be started at all. Worth recording that my first explanation was wrong: CI *does* build this project - the Linux leg's `net10.0` pass compiles it, log-confirmed - so this is not a coverage gap in the workflow, and no workflow change was made. **`Pick` and `Place` never moved the arm.** They were a delay plus a gripper action, so the operations reported `Succeeded` while nothing travelled. They now solve IK once and interpolate in joint space. **And the parts never moved**: the arm swung but the bin stayed full, because nothing tied the held object to the world state. The connector now creates 11 monitored items where it created 6, and a scripted run delivers `SeqNo=151` across 10 messages where it delivered `SeqNo=3` across 1. **The frame was smuggled through a string field.** The media provider put a base64 *data URI* of the PNG into `VisionImageReferenceDataType.Uri` - a field meant to be a *reference*, while the bytes were already returned in the inline `ByteString`. Every response therefore shipped the image twice, and a 1,311,400-byte PNG became a 1,748,536-character string against a `MaxStringLength` of 65,535: **26.7x over**. That is why raising `MaxByteStringLength`, `MaxArrayLength` and `MaxMessageSize` never helped - none of them govern a `String`. Separately the MCP tool assigned raw bytes where `ImageContentBlock` requires base64, so the wire carried `"data":"�PNG..."` - every non-UTF-8 byte replaced by U+FFFD, destroying the image and inflating the response to 6.8 MB. **The camera was aimed at nothing.** The arm's home pose, the flange scan pose the Vision model declared and the joint angles in the USD stage were three independent claims about where the camera was, and they disagreed - the declared flange orientation pointed the view 86 degrees away from the projection camera. Solving them as one thing exposed two further constraints that are easy to miss: the camera has to sit off the tool axis or it photographs its own gripper, and the IK branch has to be elbow-back or a link parks under the camera and fills the frame with the arm's own upper arm. A third was a regression this branch introduced and `Opc.Ua.Robotics.Tests` caught - aiming a straight-down camera from a point on the base's own X-Z plane puts the wrist on the J4/J6 singularity, so every motion away from home fails to solve. A 15-degree camera roll, free because the camera still looks straight down, gets 25 degrees clear, which is the margin the poses before this branch had. **The frame and the detections were different images.** The sensor declared 2448x2048, the clip endpoint 1280x1024, and the renderer produced 640x512 - not even the same aspect ratio. The ground-truth detector projects through the declared intrinsics, so its boxes lived in 2448x2048 space while an agent was handed a 640x512 picture: *"pick the red cube you can see"* arrived with coordinates that pointed off the image. Everything now agrees at 612x512, an exact 4x4 bin of the native sensor with the intrinsics scaled to match; the native size stays in the model and serial number, where it describes the hardware rather than the image. **`LatestClip` was created and never written**, so it reported `Bad_NoDataAvailable` for the life of the Server and a consumer following the model - read the published frame, call the method only if there is none - never got a frame. The dispatcher now publishes a clip it has just encoded, for every Vision server rather than this sample alone. One genuine API gap turned up on the way: `OpcUaServerOptions` exposes `MaxByteStringLength`, `MaxArrayLength` and `MaxMessageSize` and **no `MaxStringLength`**, so a Server that legitimately needs a long string could not raise the limit through the hosting API at all. Added, with tests. It is not the fix for anything above - that was a design bug - but the missing knob was real. ## Not finished - **Two projects sit below the repository's 80% line coverage.** `Opc.Ua.Vision.OpenUsd` is at 71.1% — what is left only executes with a real OpenUSD stage and plugin tree, which is not on every build agent. `Opc.Ua.AI.Inference` is now at **86.7%**, up from 12.9%: the code this branch *wrote* is covered by 25 tests, and `RestChatCompletionsBackend` — previously the whole of the shortfall — is covered by 18 more against a stubbed `HttpMessageHandler`, exercising success, refusal, throttling, retry-after, timeout and cancellation without a network. Everything else clears the bar — `Opc.Ua.Vision.Server` 92.1%, `Opc.Ua.AI` 91.4%, `.Vision.Client` 88.1%, `Opc.Ua.Vision` 85.7%, `Opc.Ua.AI.Server` 80.1%, all measured with coverlet. The CI coverage gate reports itself as advisory and non-blocking. - **`SamplesCollected` is not counted here, and `docs/Vision.md` now says so.** Section 9.4 requires a Server to count a negative example (`SceneIsEmpty` / `RetractAll` carrying a `GroundTruthLabel`) exactly as it counts one carrying geometry. `VisionNodeManager` does not, and structurally cannot: `SamplesCollected` is a property of `LearningJobType`, which the *AI Model Management* companion defines, and Vision reaches the job through a `NodeId` value rather than a Reference **precisely so this model takes no dependency on the model that defines it**. What the Server does guarantee is that the negative example survives the hop intact — both flags are carried verbatim to `IVisionFeedbackSink` — so a host that binds a learning job has everything it needs to satisfy the clause on the counter it owns. Stated in the limitations rather than left implied. ## Related Issues Was stacked on #4195, now merged. No tracking issue yet for the Vision implementation itself — happy to open one if you would like the design recorded as an ADR before this goes further. ## Checklist - [x] I have signed the [CLA](https://opcfoundation.org/license/cla/ContributorLicenseAgreementv1.0.pdf) and read the [CONTRIBUTING](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/CONTRIBUTING.md) doc. - [x] I have added tests that prove my fix is effective or that my feature works and increased code coverage. — *Types 8562, Server 4072, Client 2123, InformationModel 1063, Robotics 540, Tools 466, Vision 442, AI 74 and the restored Vision+Intent end-to-end suite 14/14, all green on net10.0. Only `.OpenUsd` (71.1%) is below the 80% bar — see Not finished.* - [x] I have added all necessary documentation. - [x] I have verified that my changes do not introduce (new) build or analyzer warnings. — *`dotnet build UA.slnx -c Release`: 0 errors, 0 warnings.* - [x] I ran **all** tests locally using the **UA.slnx** solution against at least .net **framework** and .net **10**, and all passed. — *net48: Types 8555, Client 2126, Vision 385 green. Two net48 Server tests fail (`CreateUserManagementSeamBindsTheModelToTheServerAsync`, and `DurableDataValueQueueVerifyReferenceBatchingAsync` only under parallel load); both were confirmed **pre-existing** by re-running them with the `IsInverse` change reverted, which fails identically.* - [ ] I fixed **all** failing and flaky tests in the CI pipelines and **all** CodeQL warnings. — *The net48 build legs failed because the restored end-to-end project used `ValueTask.FromResult` / `string.Create`, which do not exist on .NET Framework; fixed in `fb57522da` and verified building on every TFM. `DisposeDrainsHeldConnectionCallbackBeforeListenerDisposal` failed once on the Ubuntu Client leg — a 13 ms timing-sensitive reverse-connect disposal test that passes locally 2123/2123 and touches no browse paths.* - [ ] I have addressed **all** PR feedback received. ## Typed Vision-guided Robotics MCP workflows The branch now also makes the demo workflow first-class in the Full MCP profile: - replaces stringified Robotics intent and mission inputs with typed request schemas and exact name-or-NodeId selectors; - adds bounded operation/mission paging, stable step-to-operation identity, retained mission discovery, and `robotics_wait_mission`; - makes `vision_run_inference` return bounded typed detection, inspection, or segmentation summaries in one call; - adds same-session `robotics_vision_pick` to select a detection and submit Pick or Pick/Place work without implicitly taking authority, retrying, cancelling, or waiting; and - starts Publish workers for classic subscriptions so an independently launched OpenUSD viewer receives live robot and part updates. The migration guide documents the intentionally breaking MCP request-schema changes. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 1dab1302-19c5-4a9b-a50c-d97d389713aa Copilot-Session: a248a589-9a20-4372-868e-5d347e57001b Copilot-Session: 99d1ab42-f83a-41ab-bf3e-85bf81fadace Copilot-Session: bcbc8ac9-5abd-42a8-8bac-e10533790e2e
22 KiB
OPC UA — OpenUSD
This guide covers the client- and server-side libraries that bridge an OPC UA address space to an OpenUSD stage. For the OPC 40010 Robotics companion SDK used to label and drive robot-cell twins, see Robotics.
The work comes in two parts, covered here in turn. Part 1 — the binding model — keeps the USD scene outside OPC UA and binds process values to it. Part 2 — scene materialization — puts the scene inside the address space, so the composed prim tree becomes the node hierarchy and browsing the server is browsing the scene. The two interoperate — a Part 1 binding may target a Part 2 attribute Variable — but neither requires the other.
| Part 1 — bindings | Part 2 — scene materialization | |
|---|---|---|
| USD scene lives | outside OPC UA | inside OPC UA |
| OPC UA carries | which prim/attribute a value maps to | the prims and attributes themselves |
| Consumer | a connector that writes an external stage | a client that browses/subscribes, or exports .usda |
Both companion models are draft (experimental) models. The type NodeIds and the
Server/OpenUSD/Representationsregistry described here are subject to change until the companion specifications are ratified.
Libraries
| Package | Role |
|---|---|
OPCFoundation.NetStandard.Opc.Ua.OpenUsd |
The draft OpenUSD-binding companion model (source-generated NodeStates). |
OPCFoundation.NetStandard.Opc.Ua.OpenUsd.Client |
The generic, domain-agnostic OpenUsdConnector, the IUsdSink abstraction, and the file/mock sinks. |
OPCFoundation.NetStandard.Opc.Ua.OpenUsd.Server |
Server-side authoring helpers (UsdAssetDelivery, representation authoring). |
OPCFoundation.NetStandard.Opc.Ua.OpenUsd.Connector |
A ready-to-run console connector tool built on the client library. |
OPCFoundation.NetStandard.Opc.Ua.OpenUsd.Connector.Viewer |
Optional viewport for the connector's --view option. Renders the composed stage and exposes it as an IUsdSink. |
OPCFoundation.NetStandard.Opc.Ua.OpenUsdScene |
Part 2: the source-generated companion model, the scene document model, the .usda reader/writer, and the value-type map. |
OPCFoundation.NetStandard.Opc.Ua.OpenUsdScene.Server |
Part 2: materializer, exporter, discovery, and Part 1 interop. |
The runtime path is intentionally narrow: the connector is an OPC UA client that
discovers binding descriptors, subscribes to source Variables, converts values to
USD-shaped Variants, and writes them into one or more sinks. The optional viewer
is just another sink, so the on-disk override layer and the picture receive the
same updates.
flowchart LR
Server["OPC UA Server<br/>OpenUSD representations + bindings"]
Registry["Server/OpenUSD/Representations"]
Sources["Bound source Variables<br/>telemetry + alarms"]
History["Historized source Variables"]
Connector["OpenUsdConnector<br/>discover + subscribe + compose"]
Descriptor["RepresentationInfo + BindingInfo<br/>prim path + property + conversion"]
Sink["IUsdSink"]
File["UsdFileSink<br/>live.usda override layer"]
Viewer["Viewport sink<br/>optional --view"]
Stage["USD stage assets<br/>fetched and digest-verified"]
Server --> Registry --> Connector
Sources -->|"MonitoredItems"| Connector
History -->|"ReplayHistoryAsync"| Connector
Connector -->|"discovers"| Descriptor
Descriptor -.->|"selects prim + conversion"| Connector
Connector -->|"converted Variant"| Sink
Connector -->|"FetchServedAssetsAsync"| Stage
Sink --> File
Sink --> Viewer
Stage --> Viewer
The connector
OpenUsdConnector is a client: it discovers a server's OpenUsdRepresentation instances through the Part 1
Server/OpenUSD/Representations registry, subscribes to the bound source Variables, applies the declared conversion,
and writes the target USD attributes into an IUsdSink. It is domain-agnostic — it knows only the OpenUSD binding
model, never "pump" or "robot".
Progressive API
The simplest usage needs only a connected session and a sink:
using Opc.Ua.OpenUsd.Client;
// session is a connected ISession (for example a ManagedSession).
var sink = new UsdFileSink("live.usda");
await using var connector = new OpenUsdConnector(session, sink);
await connector.StartAsync(cancellationToken); // discover + subscribe + compose
// ... the sink now receives live updates ...
await connector.StopAsync(cancellationToken); // stop streaming
OpenUsdConnector implements IAsyncDisposable; await using (or an explicit DisposeAsync) stops streaming and
closes any connector-owned remote sessions opened for cross-server federation. The caller-provided primary session is
never closed by the connector.
Advanced behaviour is configured through OpenUsdConnectorOptions:
var options = new OpenUsdConnectorOptions
{
EnableCommands = true, // opt in to UsdToUaCommand actuation (fail-closed by default)
RemoteSessionFactory = (endpointUrl, ct) => OpenRemoteSessionAsync(endpointUrl, ct), // §5.14 cross-server federation
MaxAssetBytes = 32 * 1024 * 1024, // per-asset read cap
MaxTotalAssetBytes = 128L * 1024 * 1024, // per-fetch read cap
};
await using var connector = new OpenUsdConnector(session, sink, options, telemetry);
Values cross the boundary as Variant
IUsdSink never exposes object. A scalar attribute is a double, a colour is a three-element float array
(ArrayOf<float>), and a token/visibility value is a string — all carried as Variant:
public interface IUsdSink
{
void SetAttribute(string primPath, string propertyName, Variant value);
void SetTimeSample(string primPath, string propertyName, DateTime time, Variant value);
void ComposePrim(string primPath, OpenUsdCompositionArc arc, string? assetReference, bool active);
IDisposable BeginBatch();
}
Two sinks ship in the box:
UsdFileSinkauthors a text USD override layer (live.usda). It validates every prim-path segment and property name as a USD identifier, escapes token values, and rejects unsafe asset references, so a hostile or malformed name from the server cannot corrupt or inject into the layer.MockUsdSinkis an in-memory, thread-safe sink used by tests and diagnostics.
BeginBatch() lets a file-backed sink defer flushes; history replay uses it to author many time samples with a single
file write.
History replay and commands
ReplayHistoryAsync(startTime, endTime, ct)replays Part 11 history for everyUaHistoryToUsdbinding, following continuation points and authoring the returned values as USD time samples. Sources that do not historize degrade to zero samples without throwing.IssueCommandAsync(value, ct)actuates the opt-inUsdToUaCommandbinding. It is fail-closed: it throws unless the connector was constructed withEnableCommands = true.
Integrity
When a stage advertises a RootLayerDigest, the connector verifies it (constant-time) before authoring any opinions,
and refuses to compose on a mismatch. Served asset closures (FetchServedAssetsAsync) are streamed through the Part 5
FileType, digest-verified fail-closed, and cached under sanitized relative paths (path-traversal is defended).
Dependency injection
Both a standalone IServiceCollection extension and the fluent IOpcUaClientBuilder extension register the singleton
OpenUsdConnectorFactory; the direct constructors remain available as a non-DI fallback.
// Standalone.
services.AddOpenUsdConnector(o => o.EnableCommands = true);
// Fluent, chained onto the client builder.
services.AddOpcUa()
.AddClient(configuration)
.AddOpenUsdConnector(o => o.MaxAssetBytes = 32 * 1024 * 1024);
Resolve the factory and create a connector per connected session:
public sealed class TwinWorker(OpenUsdConnectorFactory connectors)
{
public async Task RunAsync(ISession session, IUsdSink sink, CancellationToken ct)
{
await using OpenUsdConnector connector = connectors.Create(session, sink);
await connector.StartAsync(ct);
// ...
}
}
Observability is threaded through ITelemetryContext (resolved from DI), which the factory passes to each connector.
Server-side authoring
context.CreateRepresentation(owner, stage, primPath, openUsdNs) attaches an OpenUsdRepresentation to a domain
Object and points it at a stage and prim path. The representation is an AddIn, so it is mounted with
HasAddIn — not plain HasComponent. The distinction is easy to get wrong because HasAddIn is a subtype of
HasComponent: an AddIn mounted with the wrong reference type still browses, still aggregates, and still works
end to end, so only a conformance checker notices. The IOpenUsdRepresentedType model placeholder declares the
same HasAddIn contract. CreateRepresentation is the supported authoring path; do not hand-roll a mount with
CreateInstanceOfOpenUsdRepresentationType and a manually assigned reference type. The sample servers assert the
reference type in their E2E suites.
UsdAssetDelivery.AttachStageAssets(context, stage, openUsdNs, assets) serves artist-authored USD layers through the
address space as read-only Part 5 files with SHA-256 digests, so a generic connector can fetch, verify, cache, and
render the twin with no external asset resolver. assets is an ArrayOf<ServedAsset> and the method returns the
created OpenUsdAssetState nodes as an ArrayOf<OpenUsdAssetState>.
Samples
MinimalRobotServer— a self-contained server exposing an OPC 40010 MotionDeviceSystem with two independently mobile robots. OPC 10000-210 RSL frames drive livedouble3translation/rotation, and OPC 10000-211 GPOS locations drive geospatial metadata; a generic connector renders the cell live. See Positioning.- The Robotics samples also include an agent-plus-viewer Robot Intent flow: the OpenUSD viewport shows the same robot
that the MCP tools command, and a viewport prim pick can become a robot command through
UsdViewOptions.PrimPicked. See Robot Intent and the Robotics samples. PumpDeviceIntegrationServer— a DI pump line bound to OpenUSD, including component composition and served-asset delivery.GeneratorServer— the Generators companion specification with a datasheet-driven simulation and one independent twin per configured generating set.SiteCompositionServer— a supervisory server that owns no devices and composes the machines of the pump and generator servers into a single scene through cross-server components. Render it with the connector's--federateoption. See Samples.
The connector tool
Opc.Ua.OpenUsd.Connector is a console application that connects to any server implementing the draft binding,
discovers Server/OpenUSD/Representations, subscribes, optionally fetches the served asset closure, and authors a live
live.usda override layer. It is the end-to-end reference for the client library.
dotnet run --project tools/Opc.Ua.OpenUsd.Connector -- \
--server opc.tcp://localhost:62830/MinimalRobotServer \
--fetch-assets ./stage --insecure --seconds 30
| Option | Meaning |
|---|---|
--server <url> |
Endpoint to connect to. |
--out <live.usda> |
Override layer to author. Defaults to live.usda in the working directory. |
--seconds N |
Stop after N seconds instead of waiting for Ctrl+C. |
--fetch-assets <dir> |
Download the served USD layer closure (§5.15) and compose a self-contained stage.usda. |
--insecure |
Demo only: unsecured endpoint and blanket certificate acceptance. |
--enable-commands |
Opt in to actuating UsdToUaCommand bindings (fail-closed by default). |
--command-value <double> |
Setpoint written once at start when commands are enabled. |
--view |
Render the composed stage and stream the same live values into it. |
--renderer <Auto|Storm|D3D12|Vulkan> |
Renderer preference for --view. |
--stage <stage.usda> |
Render an existing local stage instead of a fetched one. |
--plugins <dir> |
Directory holding the staged USD plugin tree, when it is not beside the connector. |
--pick-command [<prim path>] |
With --view, print picked target prim paths. |
Rendering the twin live
--view opens a viewport on the composed stage and fans every subscribed value into both the override layer and
the stage being rendered, so the twin animates in one process:
dotnet run --project tools/Opc.Ua.OpenUsd.Connector -- \
--server opc.tcp://localhost:62830/MinimalRobotServer \
--insecure --view
Without --fetch-assets or --stage, --view fetches the asset closure into a temporary directory, because a
renderer needs geometry it can resolve. Closing the window stops the session; --seconds closes it automatically.
The renderer itself lives in a separate, optional assembly, Opc.Ua.OpenUsd.Connector.Viewer
(OPCFoundation.NetStandard.Opc.Ua.OpenUsd.Connector.Viewer), which the connector loads on demand from its own
directory. That keeps the connector package free of a UI framework and a native OpenUSD payload, and lets it keep
targeting .NET Framework. When the assembly is absent, --view explains how to install it and every other option
keeps working.
Internally the viewport supplies a sink that authors into the scheduler-owned stage the renderer already owns — the
connector never opens the stage a second time. CompositeUsdSink fans values out to that sink and to UsdFileSink,
so the on-disk artefact and the picture never diverge.
The connector client API also exposes UsdViewOptions.PrimPicked, a callback that receives picked USD prim paths.
Renderer-backed pointer picking works: the OpenUSD viewer owns input handling, DPI scaling, physical-pixel conversion
and stale-revision retry, and reports hits through the host callback. Auto uses the renderer first and falls back to
the command-prim watcher only when renderer picking is unavailable, Renderer requires renderer-backed picks, and
CommandPrim uses the fallback directly. Misses do not submit intents. For the fallback, set a targetPrim
relationship, string attribute, or token attribute on UsdViewOptions.CommandPrimPath (default /World/IntentCommand)
and the callback fires when that target changes.
The viewport requires .NET 10 and the OpenUSD packages (
OpenUsd,OpenUsd.Viewer,OpenUsd.Runtime.Imaging), which are published on nuget.org, so a plain restore is enough. The RID-agnostic runtime metapackages resolve the correct native payload per RID;win-x64,linux-x64andosx-arm64are all supported. With0.8.0-alpha, a RID-less build or publish on a supported host copies that host's OpenUSD native payload. Use an explicit RID when publishing for another platform. Publish the connector and the viewport into the same directory, substituting your own RID:dotnet publish tools/Opc.Ua.OpenUsd.Connector -c Release -f net10.0 -r win-x64 --self-contained false -o out dotnet publish tools/Opc.Ua.OpenUsd.Connector.Viewer -c Release -r win-x64 --self-contained false -o outPublishing both into the same directory is what puts the optional assembly, its dependencies, and the native plugin tree where the connector looks for them.
Viewport colour, materials and cameras
Current OpenUSD packages support the live viewport features the connector samples rely on:
primvars:displayColoris authored through the managedcolor3f[]API, so DisplayColor bindings animate in the viewport instead of only appearing in the override layer.- Bound
UsdPreviewSurfacematerial networks are shaded, so material colour inputs can be used for scalar shader colour targets without requiring a duplicate displayColor fallback. - Authored stage cameras are opened automatically, so samples can frame their intended operator view.
Visibility bindings remain a good fit for binary state such as run lamps, alarm beacons and fault halos. Use them when an on/off condition should be unmistakable; they are no longer needed as a workaround for colour or material limitations.
Part 2 — scene materialization
Where the binding model above keeps the USD scene outside OPC UA, scene materialization puts the composed prim tree inside the address space: browsing the server is browsing the scene, and an ordinary Subscription on an attribute Variable is a live feed of that part of it.
Materializing a stage
UsdStage stage = UsdaReader.ReadFile("Plant.usda");
FolderState stages = context.EnsureStagesFolder(serverObject, sceneNamespaceIndex);
UsdMaterializationResult result = context.MaterializeUsdStage(stages, stage, sceneNamespaceIndex);
MaterializeUsdStage walks the composed prim tree depth first and creates, for each prim, a
HasComponent child typed by its USD typeName; for each attribute a UsdAttributeType
Variable; and for each relationship a UsdRelationshipType Object with ordered Targets and
TargetPaths.
The result carries two indexes — PrimsByPath and AttributesByPath — so a caller can bind live
data to a materialized attribute without re-browsing.
Nothing is ever dropped
The specification is emphatic that an importer must not discard what it does not understand (§8.4), because an exporter has to be able to reproduce it. So:
- an unknown typed schema stays a
UsdPrimTypecarrying itsTypeNametoken; - an unknown API schema degrades to a generic
UsdApiSchemaTypeAddIn carrying itsSchemaName; - an unknown value type is carried opaquely as
BaseDataType, with the exactSdfValueTypeNamepreserved inUsdTypeName.
Types carry USD roles
USD's color3f, normal3f, point3f and vector3f all decompose to three floats and differ
only by role. Rather than flatten that away, the model gives each its own DataType that
subtypes the built-in — the same idiom the OPC UA standard uses for Duration : Double or
UtcTime : DateTime.
Because the role type subtypes a built-in, the value bytes are unchanged: a generic client reads
a Float[3] exactly as before, while a renderer or material editor can tell a colour from a point
straight from the type system instead of parsing a string. UsdValueTypeMap implements the
mapping, and the attribute's UsdTypeName keeps it reversible even where several USD types share
one OPC UA DataType.
Live attributes
A materialized attribute is an ordinary Variable, so USD's static/time-sampled duality maps onto the OPC UA value surface in two modes a Server may mix per attribute:
- Mode A — live. The Value is server-maintained and time-varying; a Subscription delivers
changes and, where retained,
HistoryReadexposes the timeline — the OPC UA counterpart of USD time samples. RotatingxformOps and process-driven attributes use this mode. - Mode B — static. The Value is the authored default.
Driving Mode A is a Server-side responsibility. An external Part 1 connector authors into a USD sink and cannot write an in-server Variable; a Part 1 binding declares the mapping, and the Server (or a server-hosted connector) applies it.
Georeferencing
Core OpenUSD has no geodetic schema, so a georeferenced stage is expressed today through vendor extension schemas (Cesium for Omniverse, NVIDIA's geospatial schema). Those materialize through the ordinary vendor-extension mechanism — a georeference prim type as an ObjectType subtype, an anchor API schema as an AddIn.
To give a client something portable, the model also defines UsdGeoreferenceApiType (a
stage-level origin: latitude, longitude, height, EPSG code, tangent plane) and
UsdGlobeAnchorApiType (a per-prim geodetic position). When the materializer recognises a Cesium
schema it dual-authors the portable one with the same values, so a generic client reads the
anchor from one well-known type while a vendor-aware client still reads the native schema.
A partial anchor is never published: a wrong position is worse than no position.
Conversion and the round-trip contract
UsdaReader and UsdaWriter convert between .usda and the scene document model, and
UsdSceneExporter reads a materialized address space back out, so the full round trip is
.usda → UsdStage → address space → UsdStage → .usda
The contract (§7.4) is composed-scene lossless: the exported stage is prim-for-prim,
attribute-for-attribute (name, SdfValueTypeName, resolved value and array shape),
relationship-for-relationship (ordered targets), metadata-, variant-selection-, kind- and
specifier-equivalent to the input's composed result, and the recorded composition arc list is
preserved.
It is deliberately not authoring-layer lossless: the input's per-layer opinion stack, sublayer
structure and value clips are summarised as provenance under Composition/ and
RootLayerIdentifier rather than reproduced layer by layer. UsdSceneSignature computes the
equivalence used to check the contract.
Discovery and Part 1 interop
EnsureStagesFolder returns the folder stages are organized under: Part 1's
Server/OpenUSD/Stages when the bindings model is also implemented — so one connector discovers
both external-stage bindings and in-server materialized stages — or a standalone
Server/OpenUSDScene/Stages otherwise.
A Part 1 live binding may target a Part 2 attribute Variable. Part 1 ≥ 0.3.0 carries the target two ways, and a Server should author both so that path-resolving and NodeId-resolving connectors agree:
NodeId target = result.ResolveBindingTargetNodeId(
"/Plant/Pumps/Pump_1/Pump/Impeller", "xformOp:rotateZ");
Conformance units
UsdMaterializationOptions maps one-to-one onto the specification's conformance units, each
independent and additive. Scene Structure is the baseline; the rest are opt-in:
composition provenance, typed schemas, applied schemas, georeferencing, live attributes,
conversion, and Part 1 interop.