96 3D: Spatial curves and vector diagrams

9.3

Racket

96 3D: Spatial curves and vector diagrams🔗ℹ

Spatial diagram geometry is finite. A sampled curve’s centreline is separate from its rendering style. A mathematical stroke3d is resolved after projection and can retain a constant pixel width. A tube-style3d creates explicit physical tube geometry whose apparent width changes with the camera. Partial curves, reveals, and curve-following are sampled directly from the complete immutable centreline at the requested scene time; they never use a mutable updater or the preceding frame.

procedure
(stroke3d [ #:color color
#:width width
#:width-mode width-mode
#:cap cap
#:join join
#:miter-limit miter-limit
#:dash dash
#:dash-offset dash-offset
#:dash-space dash-space
#:opacity opacity
#:depth-mode depth-mode
#:depth-bias depth-bias]) → stroke3d?
  color : color-spec? = "steelblue"
  width : positive? = 2
  width-mode : (or/c 'screen 'world) = 'screen
  cap : (or/c 'butt 'square 'round) = 'round
  join : (or/c 'miter 'bevel 'round) = 'round
  miter-limit : positive? = 4
  dash : (or/c #f list? vector?) = #f
  dash-offset : finite-real? = 0
  dash-space : (or/c 'screen 'world) = width-mode
  opacity : (real-in 0 1) = 1
  depth-mode : (or/c 'test 'always 'hidden) = 'test
  depth-bias : nonnegative-real? = 1e-5

Creates an immutable mathematical-stroke style. In 'screen mode, width and default dashes are pixels after projection; in 'world mode width is a full physical diameter. A dash pattern is an even-length list or vector of positive finite lengths. 'test draws visible portions, 'hidden draws occluded portions, and 'always ignores depth.

procedure
(stroke3d? value) → boolean?
value : any/c

Recognizes a stroke style.

procedure
(stroke3d-color style) → color-spec?
style : stroke3d?

Returns stroke colour.

procedure
(stroke3d-width style) → positive?
style : stroke3d?

Returns width.

procedure
(stroke3d-width-mode style) → (or/c 'screen 'world)
style : stroke3d?

Returns width units.

procedure
(stroke3d-cap style) → (or/c 'butt 'square 'round)
style : stroke3d?

Returns endpoint-cap style.

procedure
(stroke3d-join style) → (or/c 'miter 'bevel 'round)
style : stroke3d?

Returns polyline-join style.

procedure
(stroke3d-miter-limit style) → positive?
style : stroke3d?

Returns miter limit.

procedure
(stroke3d-dash style) → (or/c #f vector?)
style : stroke3d?

Returns the validated dash pattern.

procedure
(stroke3d-dash-offset style) → finite-real?
style : stroke3d?

Returns dash phase.

procedure
(stroke3d-dash-space style) → (or/c 'screen 'world)
style : stroke3d?

Returns dash units.

procedure
(stroke3d-opacity style) → (real-in 0 1)
style : stroke3d?

Returns local opacity.

procedure
(stroke3d-depth-mode style) → (or/c 'test 'always 'hidden)
style : stroke3d?

Returns depth policy.

procedure
(stroke3d-depth-bias style) → nonnegative-real?
style : stroke3d?

Returns normalized depth bias.

procedure
(stroke3d-with-color style color) → stroke3d?
style : stroke3d?
color : color-spec?

Recolours a stroke.

procedure
(stroke3d-with-opacity style opacity) → stroke3d?
style : stroke3d?
opacity : (real-in 0 1)

Changes local opacity.

procedure
(tube-style3d [ #:radius radius
#:sides sides
#:color color]) → tube-style3d?
  radius : positive? = 1/20
  sides : exact-positive-integer? = 8
  color : color-spec? = "steelblue"

Creates the explicit physical style used when a curve should lower to a tube mesh.

procedure
(tube-style3d? value) → boolean?
value : any/c

Recognizes a tube style.

procedure
(tube-style3d-radius style) → positive?
style : tube-style3d?

Returns physical radius.

procedure
(tube-style3d-sides style) → exact-positive-integer?
style : tube-style3d?

Returns radial tessellation count.

procedure
(tube-style3d-color style) → color-spec?
style : tube-style3d?

Returns tube colour.

procedure
(point-style3d [ #:size size
#:size-mode size-mode
#:color color
#:opacity opacity
#:depth-mode depth-mode
#:depth-bias depth-bias]) → point-style3d?
  size : positive? = 8
  size-mode : (or/c 'screen 'world) = 'screen
  color : color-spec? = "cornflowerblue"
  opacity : (real-in 0 1) = 1
  depth-mode : (or/c 'test 'always 'hidden) = 'test
  depth-bias : nonnegative-real? = 1e-5

Creates a circular point-marker style. Screen size is its diameter in pixels; world size is a physical diameter projected at the point anchor.

procedure
(point-style3d? value) → boolean?
value : any/c

Recognizes a point-marker style.

procedure
(arrow-style3d [ #:length length
#:length-mode length-mode
#:width width
#:color color
#:opacity opacity
#:depth-mode depth-mode
#:depth-bias depth-bias]) → arrow-style3d?
  length : positive? = 12
  length-mode : (or/c 'screen 'world) = 'screen
  width : (or/c #f positive?) = #f
  color : color-spec? = "tomato"
  opacity : (real-in 0 1) = 1
  depth-mode : (or/c 'test 'always 'hidden) = 'test
  depth-bias : nonnegative-real? = 1e-5

Creates a screen or world arrowhead style. Its direction is taken from the final projected nondegenerate shaft segment.

procedure
(arrow-style3d? value) → boolean?
value : any/c

Recognizes an arrowhead style.

procedure
(point3d position #:id id [#:style style]) → spatial-visual?
  position : vec3?
  id : symbol?
  style : point-style3d? = (point-style3d)

Creates one finite screen/world point marker.

procedure
(curve3d? value) → boolean?
value : any/c

Recognizes a sampled spatial curve.

procedure
(line3d from to #:id id [#:style style]) → curve3d?
  from : vec3?
  to : vec3?
  id : symbol?
  style : (or/c stroke3d? tube-style3d?) = (stroke3d)

Creates a finite straight spatial line. The alias segment3d has the same arguments.

procedure
(segment3d from to #:id id [#:style style]) → curve3d?
  from : vec3?
  to : vec3?
  id : symbol?
  style : (or/c stroke3d? tube-style3d?) = (stroke3d)

Creates the same finite geometry as line3d.

procedure
(polyline3d points
#:id id
[ #:style style
#:closed? closed?
#:transform transform
#:opacity opacity]) → curve3d?
  points : (or/c list? vector?)
  id : symbol?
  style : (or/c stroke3d? tube-style3d?) = (stroke3d)
  closed? : boolean? = #f
  transform : transform3? = identity-transform3
  opacity : (real-in 0 1) = 1

Creates a sampled polyline. Adjacent repeated points are removed before stroke preparation or tube frames are formed.

procedure
(parametric-curve3d procedure
[ #:range range
#:samples samples]
#:id id
[ #:style style
#:closed? closed?]) → curve3d?
  procedure : procedure?
  range : (list/c finite-real? finite-real?) = (list 0 1)
  samples : exact-positive-integer? = 64
  id : symbol?
  style : (or/c stroke3d? tube-style3d?) = (stroke3d)
  closed? : boolean? = #f

Samples procedure at equally spaced, inclusive range endpoints. The declared samples locations are deterministic.

procedure
(tube3d points
#:id id
[ #:radius radius
#:sides sides
#:closed? closed?]
#:width-mode width-mode) → mesh3d?
  points : (or/c list? vector?)
  id : symbol?
  radius : positive? = 1/20
  sides : exact-positive-integer? = 8
  closed? : boolean? = #f
  width-mode : 'world

Creates a tube mesh using transported local frames.

procedure
(arrow3d from
to
#:id id
[ #:shaft-style shaft-style
#:tip-style tip-style]) → group3d?
  from : vec3?
  to : vec3?
  id : symbol?
  shaft-style : stroke3d? = (stroke3d #:color "tomato")
  tip-style : arrow-style3d? = (arrow-style3d #:color "tomato")

Creates a shaft and screen/world marker tip at stable descendants 'shaft and 'tip.

procedure
(double-arrow3d from
to
#:id id
[ #:shaft-style shaft-style
#:tip-style tip-style]) → group3d?
  from : vec3?
  to : vec3?
  id : symbol?
  shaft-style : stroke3d? = (stroke3d #:color "tomato")
  tip-style : arrow-style3d? = (arrow-style3d #:color "tomato")

Creates a shaft with one marker tip at each endpoint.

procedure
(with-edges3d mesh
[ #:edges edges
#:visible visible
#:hidden hidden
#:crease-angle crease-angle
#:surface surface]) → edge-overlay3d?
  mesh : mesh3d?
   edges : (or/c 'explicit 'all 'boundary 'crease 'silhouette 'feature)
= 'feature
   visible : (or/c #f stroke3d?)
= (stroke3d #:color "black" #:width 2)
  hidden : (or/c #f stroke3d?) = #f
  crease-angle : finite-real? = (/ pi 6)
  surface : (or/c 'visible 'depth-only 'none) = 'visible

Wraps a mesh with camera-prepared outlines without adding a path component. 'feature means boundary, crease, and silhouette edges. A 'depth-only surface occludes lines without painting a surface colour.

procedure
(edge-style3d? value) → boolean?
value : any/c

Recognizes a mesh-outline style.

procedure
(edge-overlay3d? value) → boolean?
value : any/c

Recognizes an outlined mesh wrapper.

procedure
(axes3d #:id id
[ #:x-range x-range
#:y-range y-range
#:z-range z-range]) → group3d?
  id : symbol?
  x-range : list? = (list -3 3)
  y-range : list? = (list -3 3)
  z-range : list? = (list -3 3)

Creates finite axes. Paths such as '(world axes x-axis), '(world axes x-ticks), and '(world axes labels x) remain stable. The final path is an invisible 3D anchor intended for follow-projected-spatial.

procedure
(coordinate-plane3d plane #:id id) → mesh3d?
plane : (or/c 'xy 'xz 'yz)
id : symbol?

Creates one finite double-sided coordinate plane.

procedure
(grid-plane3d plane #:id id) → group3d?
plane : (or/c 'xy 'xz 'yz)
id : symbol?

Creates a finite grid of physical-width spatial lines.

procedure
(basis-vectors3d #:id id) → group3d?
id : symbol?

Creates coloured i, j, and k arrows.

procedure
(vector-arrow3d vector #:id id) → group3d?
vector : vec3?
id : symbol?

Creates one arrow from the origin to vector.

procedure
(vector-components3d vector #:id id) → group3d?
vector : vec3?
id : symbol?

Creates orthogonal component arrows plus a resultant at stable descendants.

procedure
(move-along-curve3d target
curve
[ #:start start
#:end end]) → any/c
  target : spatial-path?
  curve : spatial-path?
  start : finite-real? = 0
  end : finite-real? = 1

Moves a spatial target by arc-length fraction along a curve path in the same view3d.

procedure
(orient-along-curve3d target
curve
[ #:start start
#:end end]) → any/c
  target : spatial-path?
  curve : spatial-path?
  start : finite-real? = 0
  end : finite-real? = 1

Rotates the target’s local positive x direction to the sampled tangent.

For an already-present curve path, (create '(world curve)), (uncreate '(world curve)), and (show-passing-flash '(world curve)) use the same direct curve sampling. A passing flash adds a temporary coloured tube sliver over its unchanged source curve; it disappears at each clip endpoint. The canonical vector-camera-orbit example is "examples/3d/vector-components.rkt".

I	Concepts
II	Cookbook
III	Guide
IV	Complete Example Programs
V	Reference

52	Find a task or a name
53	Modules to require
54	Scenes and sampling
55	Scene states
56	Animation requests
57	Native model details
58	Visuals
59	Geometry
60	Number Lines and Coordinate Decorations
61	Point Markers, Scatter Plots, and Filled Areas
62	Probability and Statistical Diagrams
63	Calculus lessons
64	Colors
65	Slides
66	Slide command-line tools
67	Source Programs and Authored Timelines
68	Interactive Preview and Inspection
69	Preview controls and diagnostics
70	Projects and Final Rendering
71	Project execution and cache details
72	Pict Renderer Protocol
73	3D reference map
74	3D: Objects, groups, and paths
75	3D: Cameras and projection
76	3D: Views inside a Scene
77	3D: Animating 3D objects
78	3D: Animating the 3D camera
79	3D: Cuts, caps, and section measurements
80	3D: Supplementary surface, section, and annotation bindings
81	3D: Cuts, sections, and numerical volume
82	3D: Vectors
83	3D: Linear maps and rotations
84	3D: Affine transforms
85	3D: Bounds, rays, and planes
86	3D: Spatial maps and homotopies
87	3D: Materials and lights
88	3D: Lighting inspection
89	3D: Shadow descriptors and stable bounds
90	3D: Finite-light animation
91	3D: Software finite-light evaluation
92	3D: Colour space and final output
93	3D: Relations and geometric annotations
94	3D: Projected labels
95	3D: Textured billboards
96	3D: Spatial curves and vector diagrams
97	3D: Spatial anchors and label layout
98	3D: Anchors and projected labels
99	3D: Parametric surfaces and calculus
100	3D: Adaptive, trimmed, and implicit surfaces
101	3D: Constructive solids
102	3D: Surface constructors and queries
103	3D: Meshes
104	3D: Triangle topology
105	3D: Polygonal faces
106	3D: Deterministic convex hulls
107	3D: Polyhedral duals
108	3D: Schlegel diagrams and polyhedral nets
109	3D: Conservative mesh correspondence
110	3D: Topology-safe mesh matching
111	3D: Checking and repairing mesh orientation
112	3D: Clipping, sections, and transparency
113	3D: Prepared spatial ODE trajectories and vector fields
114	3D: Seeds and streamline sets
115	3D: Poincare sections and return maps
116	3D: Equilibria and local linearization
117	3D: Flow maps and volume change
118	3D: Drawing and inspecting trajectories
119	3D: Reading prepared trajectories
120	3D: Drawing vector fields and particles
121	3D: Trajectory display
122	3D: Spatial inspection and exact picking
123	3D: Retained renderer backends
124	3D: Compiled geometry and instances
125	3D: Frame requests and results
126	3D: Software rendering and statistics
127	3D: Optional Racket/ Open GL backend
128	Experimental Derived Visuals
129	Source Package Hygiene