CDS Sample Application

A lightweight Windows desktop demo of Spatial CDS for creating 2D/3D sketches, applying geometric constraints, solving, inspecting diagnostics, and viewing recorded solver input/output. It also includes configurable robot mechanisms for inverse-kinematics demonstrations. The interface uses C++17, Dear ImGui, GLFW, and OpenGL.

This is a source package. Building and running it requires your own licensed Spatial CDS installation. The CDS SDK, license keys, SDK reference documentation, runtime DLLs, and prebuilt application are not distributed in this repository.

Requirements

• Windows x64.
• Visual Studio 2022 with Desktop development with C++, the v143 toolset, and a Windows SDK.
• Spatial CDS with x64 headers, libraries, runtime DLLs, and a valid license. This application was tested with CDS 2026.1.0.1hf.
• A locally supplied spatial_license.h defining SPATIAL_LICENSE in the SDK's include directory. Obtain this through your normal Spatial licensing setup; do not place license material in this repository.
• Internet access for the first dependency setup. The build downloads Dear ImGui 1.91.8 and GLFW 3.4 into third_party. Their upstream license files remain in those downloaded directories.

Build and run

Clone the repository, or extract the source ZIP, then open PowerShell in that folder:

git clone https://github.com/3DSSpatial/CDSSampleApp.git
cd CDSSampleApp
$env:CDSPATH = 'C:\Path\To\Your\CDS'
.\CDSSampleApp.bat

Replace the placeholder with your SDK installation root, containing include and win_b64. CDSPATH above applies to this terminal session. Set it as a Windows user environment variable if you prefer launching the BAT file by double-clicking. If the checkout is directly under <CDS>\Samples, the build can infer the SDK root.

The BAT file downloads missing GUI dependencies, builds Release | x64, copies the required SDK runtime DLLs into the local build folder, and launches bin\Release\CDSSampleApp.exe. Subsequent builds work offline once dependencies are complete. Missing dependency files are detected and downloaded again on the next build, so an interrupted setup can be retried by running the BAT file. Local binaries may contain licensing material and are not part of the public source package.

To build without launching:

powershell -NoProfile -ExecutionPolicy Bypass -File .\build.ps1 -Configuration Release

To open a replay at launch:

.\CDSSampleApp.bat "C:\Path\To\Example.CDSReplay"

For Visual Studio, first run setup.ps1, ensure CDSPATH is available to Visual Studio, open CDSSampleApp.sln, and build Release | x64. Debug is available, but the prebuilt GLFW library may produce a CRT mismatch warning in Debug.

Sketch and solve

1. Open Sketcher, choose 2D Sketch or 3D Sketch, and create geometry.
2. Select objects; Ctrl-click adds to the selection. Apply constraints or edit numeric parameters in the left panel. Angles are radians unless labelled otherwise.
3. Press Solve and inspect the result and degrees of freedom in Diagnostics. Editing invalidates the previous diagnostics. Undo solve reverts the latest solve; it is not general sketch undo.
4. Choose Solve and export replay... to save a native replay. Export performs a solve and captures its input and output, including a failed solve's diagnostics.

Wheel zooms, middle/right drag pans, and Fit view recenters the geometry. In 3D, Alt+left drag orbits and the work-plane control chooses the creation plane. Escape cancels placement. Delete removes selected objects and dependent constraints. Imported curves are edited through their defining points. Dragging uses CDS move-under-constraints after a successful solve.

IK robotics

The IK tab builds a robot immediately using lightweight link/joint primitives; it needs no modeler, CAD assets, or Interop package. Four brand-neutral layouts share the same CDS rigid-link and joint implementation:

Layout	Joint arrangement	Demonstrates
Articulated arm	6R: base, parallel shoulder/elbow, intersecting three-axis wrist; selectable 5R without final tool roll	Typical industrial arm; changing axis count.
Offset wrist	6R: parallel shoulder/elbow/first wrist axes and displaced remaining wrist axes	A different common serial-arm architecture.
Redundant arm	7R: three shoulder axes, elbow, three wrist axes	More joint freedom than a six-component tool pose.
SCARA	RRPR: two horizontal-arm rotations, vertical slide, tool yaw	Mixed rotary/prismatic joints and position control.

Use Dimensions / limits to change link lengths and apply a new home configuration. Joint jog commands actual CDS joint variables. Position leaves orientation free; Pose controls XYZ and roll/pitch/yaw on the 6/7-axis arms. Orientation is Rz(yaw) * Ry(pitch) * Rx(roll) in the robot base frame. All robot coordinates are right-handed, Z-up; positive joint angles follow the right-hand rule around the displayed arrow. Lengths are demo units and limits are illustrative, not manufacturer specifications or calibration data.

Drag the red target in the chosen XY/XZ/YZ plane through its current position. Use numeric targets, Use current, Home, or Play demo path for repeatable demos. Right drag orbits, middle drag pans, and the wheel zooms. Axis guides show the actual CDS joint frames; the green TCP and red target remain distinct when the target cannot be reached. The demo path stops if a request is not reached.

IK uses CDS move-under-constraints, resetting the incremental transform before each request. Position-only control uses a free coincident tool handle so it does not accidentally impose orientation on a rigid link. Pose control removes that handle and moves the tool axis. Exact target keeps the previous pose when a request cannot be met; otherwise CDS may find the closest valid pose. Always read the measured TCP/orientation errors, not just the constraint-solve result. If position dragging stops short (for example at a wrist singularity), one ordinary CDS point-constraint solve is attempted in an isolated mechanism. Only a validated solution is adopted; the UI identifies this as CDS position solve. This fallback can change the arm posture; it does not plan a continuous path around singularities or obstacles. Joint jogging uses SetTargetValues; simulability checks all joint commands.

Exact pose requests query GetAnalyticalInverseKinematicsSolutions after the dynamic-move run. The displayed count comes from CDS and depends on the mechanism, pose, and SDK; it is not a promise that every modified robot has analytical IK. The presets are ordinary joint models, not a second IK implementation. This is a kinematics demo without collision checking, dynamics, or motion planning.

Architecture references: six-axis articulated arms, offset-wrist kinematics, seven-axis arms, and SCARA. These sources inform the generic layouts; no branded robot model is reproduced.

View replay files

Open Replay and choose Open replay / script..., or drop a file onto the app. Sample replays opens five selected standard examples from the existing bundle:

File	Demonstrates
CreateCoincidentPoints.CDSReplay	3D point coincidence, with visible input/output movement.
CircleLineChirality1.CDSReplay	2D line/circle distance, chirality, and a fixed dimension variable.
CreateInterpolationNURBSCurve2D.CDSReplay	An interpolated NURBS curve through four points (static input/output).
CreateTangencyWithHelpPoints.CDSReplay	Line/NURBS tangency with a fixed curve help parameter.
CreateCurvePattern2D.CDSReplay	A linear circle pattern with fixed spacing variables.

The sample files are retained unchanged. They cover 2D and 3D geometry, curves, constraints, variables, and patterns without including customer captures.

• Input, Output, Play, and the slider inspect the recorded positions. Animation blends input/output; it does not show solver iterations or execute replay commands. If input and output are identical, Play shows no movement.
• Select geometry in the viewport or browser to highlight its definition in the source panel. Selecting a curve also highlights its interpolation/control points.
• The Constraints tab lists recorded constraints and patterns. Selection shows participants, dimensions, shared variables, and recorded output status. Constraint satisfaction is distinct from geometry being fixed or underdefined. Missing values/statuses are shown as Not recorded.
• Annotations: Off / Selected / All defaults to Selected. Dotted guides identify related geometry, not exact contact locations. Simple point distances get arrows; displayed dimension values are labelled as input values, not preview measurements.
• Edit input in 2D/3D sketch... imports supported input for editing and solving. Replacing a nonempty sketch requires confirmation. Export first to keep your work.
• .CDSScript playback reads adjacent <script-stem>_<Run-number>.CDSReplay files. Missing companion files are errors. Incremental frames inherit unchanged data; inherited definitions have no source line in the current snapshot.

Geometry and playback limits

CDS lines are infinite: P(t) = origin + t * direction includes both signs of t. The origin is not a ray endpoint, and coincidence constraints do not trim a line. New sketch tools may use endpoint handles as a display convention; importing a replay does not infer that trimming.

Planes and cylinders are infinite objects shown as finite wireframe previews. Unbounded conics also show finite parameter ranges; preview edges are not object boundaries. The inspector identifies these cases. Parabolas and hyperbolas follow the SDK's directed parameterization. Spheres use wireframe circles, and curves are sampled polylines. Intermediate animation is a visual blend, not a solved state.

The viewer supports common primitives and controlled/interpolated NURBS with point conditions, including automatic degree 0. Editing supports common geometric and dimensional constraints, shared variables, help parameters, and 2D linear patterns. Equations, dynamic move sections, mixed/multiple sketch frames, 3D controlled curves, non-XY sketch planes, and unsupported options remain playback-only or report an import error. Unknown geometry is flagged. 2D playback uses sketch-local coordinates. This application is not a complete CDS replay interpreter.

Recording and files

Diagnostics > Replay / Debug controls the output folder, prefix, and recording mode. Recording starts Off each launch. Replay file per solve writes uniquely named native captures; preferences are stored locally in replay-settings.txt. The default recording directory is <app folder>\replays when using the BAT file. Browsing a replay does not create a recording.

Export writes to a temporary capture folder and atomically replaces the requested destination after validation. Opening supports Unicode paths; the SDK trace writer requires an output path representable in the Windows code page. Use an ASCII-only output path if the SDK rejects it. Failed exports report their capture location.

Replay files may contain proprietary geometry and diagnostics. Keep your own recordings, license headers, SDK files, build outputs, and local preferences private. Native script recording is not exposed; existing script playback is supported.

Contributing

Keep the application small: C++17, Dear ImGui, GLFW, and OpenGL, with no service or browser runtime. Maintain this README as the single setup and development guide. Use the documentation supplied with your licensed SDK for CDS API details.

Use one working checkout with origin pointing to https://github.com/3DSSpatial/CDSSampleApp.git; no parallel private repository is needed. Private SDK documentation and personal notes may stay in a local docs/ folder, which Git ignores. These files are not shipped or downloaded by the app. Keep license material in your SDK installation, outside the checkout. Do not force-add ignored documentation, local recordings, or build outputs.

After repository access is available, publish master with git push -u origin master. Use git pull --ff-only before subsequent work and review git status and the staged diff before committing. Direct pushes depend on the organization's branch rules; use a feature branch and pull request when reviews are required. Both workflows use this same checkout.

Location	Responsibility
src/App.*, src/main.cpp	Application setup and navigation.
src/Sketcher2D.*, src/Sketcher3D.*	Sketch interaction and rendering.
src/CDSSession.*	Solver lifetime, solve/undo, recording and export.
src/ReplayDocument.*	Bounded parsing, script reconstruction and geometry sampling.
src/ReplayPanel.*	Replay browser, inspection, annotations and source view.
src/SketchReplay.cpp	Validated, transactional imports.
src/FileIO.*	File dialogs, paths and atomic writes.
src/DiagnosticsPanel.*	Solver diagnostics and recording settings.
src/IKRobot.*, src/IKModule3D.*	CDS robot mechanisms/IK and the lightweight UI/renderer.

Build Release and check 2D/3D creation, solving, editing, export/reopen, and supplied replays after relevant changes. Verify unsupported imports preserve the current sketch and recording stops when disabled. Compare geometry with native CDS evaluation; do not infer missing constraints or trimming. Invalidate diagnostics and solve undo after edits, and remove dependent constraints before geometry. Use CDS type checks/casts across the SDK DLL boundary. For IK changes, verify all four layouts and the 5-axis variant: positive joint directions, rigid link shapes, mechanism DOF, limits, position/pose switching, repeated demo paths, and recovery after unreachable or invalid targets. Include an unreachable exact target followed by joint jog, position IK, and exact pose IK to catch stale native solver state. Test configuration failures without destroying the previous robot. Keep native constraint status separate from actual target accuracy.

Do not commit SDK documentation, SDK binaries, license material, customer data, downloaded dependencies, build outputs, or temporary test captures. Only the five selected standard sample replays are included in the public package.