Files
5899354441 Clarify documentation, migration guidance, and SDK selection (#4823)
# Description

Remove stock phrasing and correct misleading or inconsistent technical
documentation. The initial two passes covered 367 Markdown files,
followed by an interactive review of 169 editorial flags. The U5
interpretation originally deferred in that review has since received the
upstream Mantis answer recorded by #4843; remaining server/spec
follow-ups stay explicit in the CTT log.

- Correct package responsibilities, migration steps, API names,
ownership, protocol descriptions and links. Keep bundled migration
guides synchronized. Preserve historical conclusions as historical
records with separate re-check notes.
- Provide at least two rendered TOC levels throughout `docs/`. Convert
appropriate architecture figures to Mermaid without changing code
examples, transcripts or historical quotations.
- Address the October 19 feedback with concrete setup/migration
instructions, corrected certificate paths and PubSub names, shorter
repeated caveats, consistent XML comments, and a full review of the
Concepts guide. Retain #4839's API corrections.
- Integrate #4841's runtime/performance guidance and review
incoming/recent prose. Preserve dated measurements rather than claiming
new benchmark runs; clarify allocation ratios, startup-only processor
settings, JIT warm-up and the benchmark commit's scope. Missing raw
measurement artifacts and repeat ranges remain tracked by #4842.
- Merge master through `e8c5d800a` in `32c6394b7`. Resolve the CTT log
conflict using the updated Mantis states and OPC answers, retaining
historical framing and re-checks for C28/C32/C43.
- Address the latest naming/index feedback in `adb5bf693`: rename the
guides to `docs/WotCon.md` and `docs/WotNodeSetConversion.md`; move the
provider and DataType-declaration contracts into the conversion guide
and remove `docs/WoT.md`. Rename `samples/DI` to `samples/Di` and
`samples/Isa95` to `samples/ISA95`. Add content-index READMEs to Di,
FluentApi, ISA95, Lds and PubSub; update solution entries, project
references, Docker/CI paths, test fixture paths and documentation links
with exact casing.

**WoT guide scope.** This branch retains the detailed conversion guide
that #4758 had replaced with an anchor stub. Conversion limits, verified
document sets, preservation rules and provider ownership now live
together in `WotNodeSetConversion.md`; binding/runtime guidance remains
in `WotBindings.md` and `WotCon.md`. The design-rationale/test-ledger
prose was shortened, the oversized argument-table cell moved into its
section, and existing anchors preserved.

**SDK policy is a separate, explicit user-directed change.**
`global.json` sets a stable minimum of `10.0.400`, `rollForward:
latestMajor`, and `allowPrerelease: false`. Newer major SDKs are
permitted; CI's explicit SDK pins are unchanged. README, GettingStarted,
DeveloperGuide and Recycling instructions reflect the possible analyzer
differences. The image-contract regression fix accepts compatible stable
SDK images instead of requiring exact equality with the floor.

The latest four rename/index threads are resolved after publication.
Three older threads remain open: universal obsolete-removal timing,
unconditional nonce-strength wording, and a blanket Vision NativeAOT
claim. Existing implementation/evidence constraints are explained in
their inline replies. The two-level TOCs remain as requested.

## Validation

- `git diff --check` and staged diff checks: passed. The untouched
upstream AutoID NodeSet retains its provenance bytes, including two
existing license-header trailing spaces.
- `.\.azurepipelines\validate-migration-plugin.ps1`: passed; 15 bundled
migration documents and manifests synchronized.
- Documentation/path validation: **101** documents retain two rendered
TOC levels (**2,228** entries), with idempotent formatting. **52** new
relative links and their anchors passed exact-case checks. No tracked
references to the old guide/sample paths remain. Both relocated
provider-contract sections are preserved in the destination.
- `dotnet sln UA.slnx list`: passed; shows the renamed Di/ISA95 projects
and the existing FluentApi/Lds/PubSub projects. Updated solution and
pump ProjectReference paths also passed exact-case existence checks.
- Latest focused commands, run from the repository root:

```powershell
# Passed: 61 channel send-order and reconnect tests.
dotnet test tests\Opc.Ua.Core.Tests\Opc.Ua.Core.Tests.csproj -p:CustomTestTarget=net10.0 --filter 'FullyQualifiedName~UaSCBinaryChannelSendOrderTests|FullyQualifiedName~TcpReconnectKeyAgreementTests' --verbosity minimal

# Passed: 5 pump datasheet tests; builds the renamed pump sample.
dotnet test tests\Opc.Ua.Di.Tests\Opc.Ua.Di.Tests.csproj -p:CustomTestTarget=net10.0 --filter 'FullyQualifiedName~PumpDatasheetConformanceTests' --verbosity minimal

# Passed: 4 repository NodeSet path/round-trip tests, including the moved pump models.
dotnet test tests\Opc.Ua.Types.Tests\Opc.Ua.Types.Tests.csproj -p:CustomTestTarget=net10.0 --filter 'FullyQualifiedName~RepositorySourceSurvivesSerializedLinkedPartitionsAsync' --verbosity minimal

# Passed: build, zero warnings/errors.
dotnet build samples\ISA95\MinimalIsa95Server\MinimalIsa95Server.csproj -p:CustomTestTarget=net10.0 -f net10.0 --verbosity minimal

# Passed: dependent sample-test project build, zero warnings/errors.
dotnet build tests\Opc.Ua.WotCon.Samples.Tests\Opc.Ua.WotCon.Samples.Tests.csproj -p:CustomTestTarget=net10.0 -f net10.0 --verbosity minimal
```

Earlier focused integration checks passed 2,620 tests across AutoID,
event queues/scheduling, source generation, MCP/package profiles and
WoT. Both reviewed Mermaid diagrams rendered locally without network
access. These checks are not a full solution run.

The full solution has **not** been rerun for this review. Earlier
`dotnet test UA.slnx -p:CustomTestTarget=net10.0 --verbosity quiet` did
not pass: three AOT projects rejected VSTest and 20 Vision tests failed
during graphics initialization with `OutOfMemoryException`. Remaining
long-running tests were stopped at the user's request. A focused Vision
rerun passed 558 tests and reproduced those 20 failures. The earlier
`dotnet test UA.slnx -p:CustomTestTarget=net48 --verbosity quiet` was
blocked by the former SDK pin and was not retried after the policy
change. The user approved proceeding with those limitations documented;
current remote CI is not claimed green.

## Related Issues

- Follow-up #4842 tracks the requested 2.0.2+ benchmark/tuning and
diagnostic-tool documentation refresh. #4841 supplies documentation and
earlier results, not all newly requested measurements.
- #4758 explains the conversion guide's earlier consolidation; the
current provider contracts are now consolidated into
`WotNodeSetConversion.md`.
- #4839 supplies the reviewed API corrections; #4843 supplies the
updated CTT issue record.
- The original prose cleanup and SDK policy were user-requested without
a source issue. No new runtime architecture is introduced by these
documentation edits.

## Checklist

_Put an `x` in the boxes that apply. You can complete these step by step
after opening the PR._

- [ ] 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.
- [ ] I have added tests that prove my fix is effective or that my
feature works and increased code coverage.
- [x] I have added all necessary documentation.
- [ ] I have verified that my changes do not introduce (new) build or
analyzer warnings.
- [ ] I ran **all** tests locally using the **UA.slnx** solution against
at least .net **framework** and .net **10**, and all passed.
- [ ] I fixed **all** failing and flaky tests in the CI pipelines and
**all** CodeQL warnings.
- [ ] I have addressed **all** PR feedback received.

---------

Co-authored-by: Roman Ettlinger <romanett98@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 10:10:55 +02:00

416 lines
16 KiB
Plaintext

#usda 1.0
(
doc = """Bin-picking work cell for the OPC UA Vision guided-picking sample.
The scene uses a branch-stable four-axis palletizer sized for this cell and
the parallel gripper shared with IntentEnabledRobot. It adds a bin of mixed
parts, a fixture to place them onto, and an eye-in-hand camera parented to
the flange so the view moves with the arm. This is the worked example
reproduced from the OPC UA Robotics-Vision Addendum: frame tree
world -> robot_base -> flange -> gripper_tcp with camera_eih on the flange.
Rendering contract:
Keep the single DomeLight at intensity 1000. In the sample's original
lighting tests, a DistantLight bright enough to show geometry washed every
part to white, preventing selection of "the red part". Historical DomeLight
captures measured red (220, 37, 37), green (37, 208, 49), blue (37, 73, 233).
Re-check captured colors after lighting, material or renderer changes.
Frame tree contract:
- /World is the WorldFrame origin.
- /World/Robot/Palletizer/Base is the robot_base frame.
- /World/Robot/Palletizer/Base/J1/J2/J3/Leveling/J4/Flange is the flange
(mechanical interface).
- /World/Robot/Palletizer/.../Flange/Camera is the eye-in-hand camera prim
(UsdGeomCamera) that the Vision sensor renders from.
- /World/Robot/Palletizer/.../Flange/Gripper/Tcp is the gripper_tcp frame.
The camera is a child of the flange with no stack reset, so it travels with
the arm as a real eye-in-hand sensor does: rotateY = -90 turns its view axis
onto the flange +X tool direction. The authored joint angles put the flange
over the bin at the sample's start pose, so it opens looking into the bin.
"""
defaultPrim = "World"
metersPerUnit = 1
upAxis = "Z"
)
def Xform "World"
{
# A fixed observer for the viewport, distinct from the eye-in-hand sensor on the
# flange. Opening the viewer on /World/Robot/.../Camera shows what the tool sees; this
# one shows the cell working, which is what someone watching the robot wants.
#
# It sits on the -Y side so +X reads left to right, which is what puts the fixture on
# the left and the bin on the right. This is deliberately a low, centred front view:
# the table surface is nearly edge-on, its legs stay visible, and the complete wrist,
# gripper, bin and stack can be judged against one another throughout a cycle.
#
# The numbers were fitted to a reference framing and then corrected against what the
# viewer actually rendered, because the analytic placement and the rendered result did
# not agree - the framing came out offset and over-scaled. Treat them as measured
# rather than derived: change one and the framing has to be re-checked against a
# capture, not just recomputed.
def Camera "ObserverCamera"
{
token projection = "perspective"
float focalLength = 31.6
float horizontalAperture = 20.955
float verticalAperture = 16.989
float2 clippingRange = (0.1, 100.0)
double3 xformOp:translate = (0.500, -5.400, 1.300)
double xformOp:rotateX = 75.50
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateX"]
}
def Xform "Lights"
{
def DomeLight "Sky"
{
float inputs:intensity = 1000
color3f inputs:color = (1.0, 1.0, 1.0)
}
}
def Xform "Robot"
{
def Cylinder "PedestalRiser"
{
uniform token axis = "Z"
double height = 0.2000
double radius = 0.1650
color3f[] primvars:displayColor = [(0.16, 0.17, 0.18)] (
interpolation = "constant"
)
double3 xformOp:translate = (0, 0, 0.8200)
uniform token[] xformOpOrder = ["xformOp:translate"]
}
def Xform "Palletizer" (
references = @palletizer-arm.usda@</Palletizer>
)
{
double3 xformOp:translate = (0, 0, 0.9200)
uniform token[] xformOpOrder = ["xformOp:translate"]
over "Base"
{
over "J1"
{
double xformOp:rotateZ = 0.000
over "J2"
{
double xformOp:rotateY = 31.513
over "J3"
{
double xformOp:rotateY = -65.890
over "Leveling"
{
double xformOp:rotateY = 124.377
over "J4"
{
double xformOp:rotateX = 90.000
over "Flange"
{
def Xform "Gripper" (
references = @palletizer-gripper.usda@</PalletizerGripper>
)
{
}
def Camera "Camera"
{
token projection = "perspective"
float focalLength = 12.24
float horizontalAperture = 14.688
float verticalAperture = 12.288
float2 clippingRange = (0.02, 5.0)
double3 xformOp:translate = (0.0200, 0.0000, 0.1600)
double xformOp:rotateY = -90
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateY"]
}
}
}
}
}
}
}
}
}
}
def Xform "Floor"
{
def Cube "Slab"
{
double size = 1
color3f[] primvars:displayColor = [(0.36, 0.37, 0.40)] (
interpolation = "constant"
)
double3 xformOp:translate = (0, 0, -0.0250)
double3 xformOp:scale = (2.4000, 1.8000, 0.0250)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
}
def Xform "Bench"
{
def Cube "Top"
{
double size = 1
color3f[] primvars:displayColor = [(0.58, 0.60, 0.60)] (
interpolation = "constant"
)
# The work surface is z = 0.720. The robot base is independently raised
# to z = 0.920 on PedestalRiser, so the wrist no longer has to fold back
# on itself to reach parts lying close to the table.
double3 xformOp:translate = (0, 0, 0.6850)
double3 xformOp:scale = (1.4000, 0.9000, 0.0700)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
def Cube "LegA"
{
double size = 1
color3f[] primvars:displayColor = [(0.22, 0.23, 0.24)] (
interpolation = "constant"
)
double3 xformOp:translate = (0.5800, 0.3300, 0.3250)
double3 xformOp:scale = (0.0250, 0.0250, 0.6500)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
def Cube "LegB"
{
double size = 1
color3f[] primvars:displayColor = [(0.22, 0.23, 0.24)] (
interpolation = "constant"
)
double3 xformOp:translate = (-0.5800, 0.3300, 0.3250)
double3 xformOp:scale = (0.0250, 0.0250, 0.6500)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
def Cube "LegC"
{
double size = 1
color3f[] primvars:displayColor = [(0.22, 0.23, 0.24)] (
interpolation = "constant"
)
double3 xformOp:translate = (0.5800, -0.3300, 0.3250)
double3 xformOp:scale = (0.0250, 0.0250, 0.6500)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
def Cube "LegD"
{
double size = 1
color3f[] primvars:displayColor = [(0.22, 0.23, 0.24)] (
interpolation = "constant"
)
double3 xformOp:translate = (-0.5800, -0.3300, 0.3250)
double3 xformOp:scale = (0.0250, 0.0250, 0.6500)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
}
def Xform "Bin"
{
def Cube "BinFloor"
{
double size = 1
color3f[] primvars:displayColor = [(0.42, 0.32, 0.20)] (
interpolation = "constant"
)
double3 xformOp:translate = (0.6000, 0.0000, 0.7160)
double3 xformOp:scale = (0.2800, 0.2400, 0.0060)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
def Cube "BinWallN"
{
double size = 1
color3f[] primvars:displayColor = [(0.42, 0.32, 0.20)] (
interpolation = "constant"
)
double3 xformOp:translate = (0.6000, 0.1170, 0.7330)
double3 xformOp:scale = (0.2800, 0.0060, 0.0400)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
def Cube "BinWallS"
{
double size = 1
color3f[] primvars:displayColor = [(0.42, 0.32, 0.20)] (
interpolation = "constant"
)
double3 xformOp:translate = (0.6000, -0.1170, 0.7330)
double3 xformOp:scale = (0.2800, 0.0060, 0.0400)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
def Cube "BinWallE"
{
double size = 1
color3f[] primvars:displayColor = [(0.42, 0.32, 0.20)] (
interpolation = "constant"
)
double3 xformOp:translate = (0.7370, 0.0000, 0.7330)
double3 xformOp:scale = (0.0060, 0.2400, 0.0400)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
def Cube "BinWallW"
{
double size = 1
color3f[] primvars:displayColor = [(0.42, 0.32, 0.20)] (
interpolation = "constant"
)
double3 xformOp:translate = (0.4630, 0.0000, 0.7330)
double3 xformOp:scale = (0.0060, 0.2400, 0.0400)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
}
def Xform "Fixture"
{
def Cube "Base"
{
double size = 1
color3f[] primvars:displayColor = [(0.20, 0.20, 0.22)] (
interpolation = "constant"
)
double3 xformOp:translate = (-0.6000, 0.0000, 0.7200)
double3 xformOp:scale = (0.1400, 0.1400, 0.0180)
uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:scale"]
}
def Cylinder "PegA"
{
uniform token axis = "Z"
double height = 0.0400
double radius = 0.0090
color3f[] primvars:displayColor = [(0.95, 0.85, 0.20)] (
interpolation = "constant"
)
double3 xformOp:translate = (-0.6500, 0.0500, 0.7490)
uniform token[] xformOpOrder = ["xformOp:translate"]
}
def Cylinder "PegB"
{
uniform token axis = "Z"
double height = 0.0400
double radius = 0.0090
color3f[] primvars:displayColor = [(0.95, 0.85, 0.20)] (
interpolation = "constant"
)
double3 xformOp:translate = (-0.5500, 0.0500, 0.7490)
uniform token[] xformOpOrder = ["xformOp:translate"]
}
def Cylinder "PegC"
{
uniform token axis = "Z"
double height = 0.0400
double radius = 0.0090
color3f[] primvars:displayColor = [(0.95, 0.85, 0.20)] (
interpolation = "constant"
)
double3 xformOp:translate = (-0.6000, -0.0500, 0.7490)
uniform token[] xformOpOrder = ["xformOp:translate"]
}
}
# Each part is an Xform carrying a single xformOp:transform, with its shape as a child.
# The OpenUSD live binding drives the parent's transform, and the viewer sink authors
# that op as a whole matrix - composing translation with a default identity rotation and
# unit scale. Rotation and scale therefore have to live somewhere the binding does not
# overwrite, which is the child. The composition is unchanged: the shape is scaled and
# rotated about its own origin, then the parent translates it.
def Xform "Parts"
{
def Xform "RedCube"
{
matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0.5200, -0.0800, 0.7400, 1) )
uniform token[] xformOpOrder = ["xformOp:transform"]
def Cube "Shape"
{
double size = 0.0400
color3f[] primvars:displayColor = [(0.90, 0.15, 0.15)] (
interpolation = "constant"
)
double xformOp:rotateZ = 20
uniform token[] xformOpOrder = ["xformOp:rotateZ"]
}
}
def Xform "GreenCylinder"
{
matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0.6700, 0.0800, 0.7350, 1) )
uniform token[] xformOpOrder = ["xformOp:transform"]
def Cylinder "Shape"
{
uniform token axis = "Z"
double height = 0.0300
double radius = 0.0200
color3f[] primvars:displayColor = [(0.15, 0.85, 0.20)] (
interpolation = "constant"
)
}
}
def Xform "BlueSphere"
{
matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0.6800, -0.0800, 0.7440, 1) )
uniform token[] xformOpOrder = ["xformOp:transform"]
def Sphere "Shape"
{
double radius = 0.0240
color3f[] primvars:displayColor = [(0.15, 0.30, 0.95)] (
interpolation = "constant"
)
}
}
def Xform "YellowSlab"
{
matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0.5200, 0.0600, 0.7290, 1) )
uniform token[] xformOpOrder = ["xformOp:transform"]
def Cube "Shape"
{
double size = 1
color3f[] primvars:displayColor = [(0.95, 0.85, 0.15)] (
interpolation = "constant"
)
double3 xformOp:scale = (0.0640, 0.0320, 0.0180)
double xformOp:rotateZ = -15
uniform token[] xformOpOrder = ["xformOp:rotateZ", "xformOp:scale"]
}
}
def Xform "OrangeBrick"
{
matrix4d xformOp:transform = ( (1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0.6000, 0.0000, 0.7320, 1) )
uniform token[] xformOpOrder = ["xformOp:transform"]
def Cube "Shape"
{
double size = 1
color3f[] primvars:displayColor = [(0.95, 0.45, 0.10)] (
interpolation = "constant"
)
double3 xformOp:scale = (0.0500, 0.0280, 0.0240)
double xformOp:rotateZ = 40
uniform token[] xformOpOrder = ["xformOp:rotateZ", "xformOp:scale"]
}
}
}
}