58.2 Shapes and Path Visuals

9.3

Racket

58.2 Shapes and Path Visuals🔗ℹ

Use circle and rectangle for the two basic shape Visuals, make-path-visual for existing local geometry, and line or polygon for points supplied in a containing coordinate system. The catalogue constructors below reuse ordinary path and group Visuals.

58.2.1 Circle Visuals

58.2.2 Rectangle Visuals

58.2.3 Path Visuals

58.2.4 Mathematical Shape Catalogue

58.2.1 Circle Visuals🔗ℹ

procedure
(circle #:id id
[ #:center center
#:rotation rotation
#:scale scale
#:opacity opacity
#:radius radius
#:fill fill
#:stroke stroke
#:stroke-width stroke-width]) → circle-visual?
  id : symbol?
  center : vec2? = origin
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  radius : (and/c finite-real? positive?) = 1
  fill : any/c = "dodgerblue"
  stroke : any/c = "black"
  stroke-width : (and/c finite-real? (>=/c 0)) = 2

Creates a semantic circle. The id argument is required and must be a symbol. center, rotation, and scale form its affine transform. The center is in the Visual’s containing coordinate system: world coordinates at the top level and group-local coordinates for a child. radius is measured in local world units before scale is applied.

The built-in Pict renderer treats fill and stroke as color values and stroke-width as a Pict border width. These style values are stored without adapter-specific validation.

Circle Visuals implement gen:visual, gen:affine-visual, gen:opacity-visual, and gen:stroke-width-visual. The opacity value multiplies the complete rendered circle after renderer dispatch.

procedure
(circle-visual? value) → boolean?
value : any/c

Returns #t when value is a built-in circle Visual.

procedure
(circle-visual-radius circle) → (and/c finite-real? positive?)
circle : circle-visual?

Returns the unscaled local radius in world units.

Inspect local geometry without rendering it.

Examples:

> (define disk (circle #:id 'disk #:radius 3/4))
> (circle-visual-radius disk)
3/4

procedure
(circle-visual-fill circle) → any/c
circle : circle-visual?

Returns the stored fill style.

procedure
(circle-visual-stroke circle) → any/c
circle : circle-visual?

Returns the stored stroke style.

procedure
(circle-visual-stroke-width circle)
→ (and/c finite-real? (>=/c 0))
circle : circle-visual?

Returns the stored stroke width.

58.2.2 Rectangle Visuals🔗ℹ

procedure
(rectangle #:id id
[ #:center center
#:rotation rotation
#:scale scale
#:opacity opacity
#:width width
#:height height
#:fill fill
#:stroke stroke
#:stroke-width stroke-width]) → rectangle-visual?
  id : symbol?
  center : vec2? = origin
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  width : (and/c finite-real? positive?) = 2
  height : (and/c finite-real? positive?) = 1
  fill : any/c = "goldenrod"
  stroke : any/c = "black"
  stroke-width : (and/c finite-real? (>=/c 0)) = 2

Creates a semantic rectangle. The untransformed rectangle is centered at its reference position and is axis-aligned in local coordinates. The center value is in the Visual’s containing coordinate system: world coordinates at the top level and group-local coordinates for a child. Width and height are measured before scale and rotation are applied.

The id argument is required. Style values are stored for an adapter to interpret. Rectangle Visuals implement the basic, affine, opacity, and stroke-width Visual protocols. The opacity value multiplies the complete rendered rectangle.

procedure
(rectangle-visual? value) → boolean?
value : any/c

Returns #t when value is a built-in rectangle Visual.

procedure
(rectangle-visual-width rectangle)
→ (and/c finite-real? positive?)
rectangle : rectangle-visual?

Returns the unscaled local width in world units.

procedure
(rectangle-visual-height rectangle)
→ (and/c finite-real? positive?)
rectangle : rectangle-visual?

Returns the unscaled local height in world units.

procedure
(rectangle-visual-fill rectangle) → any/c
rectangle : rectangle-visual?

Returns the stored fill style.

procedure
(rectangle-visual-stroke rectangle) → any/c
rectangle : rectangle-visual?

Returns the stored stroke style.

procedure
(rectangle-visual-stroke-width rectangle)
→ (and/c finite-real? (>=/c 0))
rectangle : rectangle-visual?

Returns the stored stroke width.

58.2.3 Path Visuals🔗ℹ

A path Visual combines local path-geometry with identity, affine placement, fill, stroke, and cosmetic stroke width. Its geometry may contain line segments, cubic Bézier segments, or both. It implements gen:visual, gen:affine-visual, and gen:opacity-visual.

The Visual’s reference position is the translation component of its affine transform. Its path points remain local model data. Scale and rotation are applied around the local origin before the Visual is translated to its reference position.

procedure
(make-path-visual path
#:id id
[ #:center center
#:rotation rotation
#:scale scale
#:opacity opacity
#:fill fill
#:stroke stroke
#:stroke-width stroke-width]) → path-visual?
  path : path-geometry?
  id : symbol?
  center : vec2? = origin
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  fill : any/c = #f
  stroke : any/c = "black"
  stroke-width : (and/c finite-real? (>=/c 0)) = 2

Creates a semantic path Visual from local path geometry. The id argument is required. center is the Visual’s reference position in its containing coordinate system. It is a world-space point at the top level and a group-local point when the Visual is a child. Rotation is measured counter-clockwise in radians, and scale is applied to local x and y coordinates before rotation. opacity is global and is applied to the complete rendered path after renderer dispatch.

The built-in Pict renderer interprets a false fill as transparent and a false stroke as no outline. Other style values are passed to the Racket drawing backend as color values. Stroke width is cosmetic and measured in output pixels; semantic scale does not multiply it.

Empty path geometry is accepted and produces a transparent one-pixel Pict in the built-in renderer.

procedure
(path-visual? value) → boolean?
value : any/c

Returns #t when value is a built-in path Visual.

procedure
(path-visual-path visual) → path-geometry?
visual : path-visual?

Returns visual’s local semantic path geometry. The returned geometry has not been translated, rotated, scaled, or converted to pixels.

procedure
(path-visual-fill visual) → any/c
visual : path-visual?

Returns the stored fill style. The built-in renderer uses it only for closed subpaths. A false value disables filling.

procedure
(path-visual-stroke visual) → any/c
visual : path-visual?

Returns the stored stroke style. A false value disables stroking in the built-in renderer.

procedure
(path-visual-stroke-width visual)
→ (and/c finite-real? (>=/c 0))
visual : path-visual?

Returns the stored cosmetic stroke width.

procedure
(path-visual-with-path visual path) → path-visual?
visual : path-visual?
path : path-geometry?

Returns a new path Visual with its local geometry replaced by path. Identity, affine transform, opacity, fill, stroke, and stroke width are preserved. The original Visual is unchanged.

procedure
(line start
end
#:id id
[ #:rotation rotation
#:scale scale
#:opacity opacity
#:stroke stroke
#:stroke-width stroke-width]) → path-visual?
  start : vec2?
  end : vec2?
  id : symbol?
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  stroke : any/c = "black"
  stroke-width : (and/c finite-real? (>=/c 0)) = 2

Creates an open path Visual between two points in one containing coordinate system. The points are world-space values when the result is top level and local values when the result is placed in a group. start and end must differ.

The constructor uses the midpoint of the two points as the Visual’s reference position and subtracts that midpoint from both stored path points. The local line is therefore centered at the origin. Rotation and scale are applied around that midpoint. The fill style is always #f. The optional opacity value is preserved as semantic global opacity.

For example:

(line (vec2 -2 0)
      (vec2 2 0)
      #:id 'axis
      #:stroke "navy"
      #:stroke-width 3)

The reference position is the midpoint of the supplied endpoints.

Examples:

> (define segment (line (vec2 -2 0) (vec2 4 0) #:id 'segment))
> (vec2-x (visual-position segment))
1

procedure
(polygon vertices
#:id id
[ #:rotation rotation
#:scale scale
#:opacity opacity
#:fill fill
#:stroke stroke
#:stroke-width stroke-width]) → path-visual?
  vertices : (listof vec2?)
  id : symbol?
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  fill : any/c = "cornflowerblue"
  stroke : any/c = "black"
  stroke-width : (and/c finite-real? (>=/c 0)) = 2

Creates a closed path Visual through at least three vertices in one containing coordinate system. The vertices are world-space values at the top level and local values when the result is placed in a group. Vertex order is significant.

The constructor computes the center of the vertices’ axis-aligned bounding box and uses it as the Visual’s reference position. It subtracts that center from every stored path point, so scale and rotation occur around the bounding-box center. The constructor does not calculate a polygon centroid.

The closing edge from the last vertex to the first is implicit. Do not repeat the first vertex merely to close the polygon; repeating it adds a zero-length segment before the implicit closing edge. The optional opacity value is stored as semantic global opacity.

58.2.4 Mathematical Shape Catalogue🔗ℹ

The shape catalogue provides a compact family of path-backed shapes. Except for the two convenience groups, each constructor returns an ordinary path-visual? with the usual affine placement, opacity, fill, and stroke protocols. They do not introduce renderer-specific leaf classes; the existing path renderer draws their line and cubic geometry, including odd-even holes in annulus.

procedure
(ellipse #:id id
[ #:center center
#:width width
#:height height
#:rotation rotation
#:scale scale
#:opacity opacity
#:fill fill
#:stroke stroke
#:stroke-width stroke-width]) → path-visual?
  id : symbol?
  center : vec2? = origin
  width : (and/c finite-real? positive?) = 2
  height : (and/c finite-real? positive?) = 1
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  fill : any/c = "cornflowerblue"
  stroke : any/c = "black"
  stroke-width : stroke-width? = 2

Creates a cubic Bézier ellipse centered at center. Width and height are unscaled world dimensions. Rotation and scale are applied around the centre.

procedure
(annulus #:id id
[ #:center center
#:inner-radius inner-radius
#:outer-radius outer-radius
#:rotation rotation
#:scale scale
#:opacity opacity
#:fill fill
#:stroke stroke
#:stroke-width stroke-width]) → path-visual?
  id : symbol?
  center : vec2? = origin
  inner-radius : (and/c finite-real? positive?) = 1/2
  outer-radius : (and/c finite-real? positive?) = 1
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  fill : any/c = "cornflowerblue"
  stroke : any/c = "black"
  stroke-width : stroke-width? = 2

Creates a closed ring with an odd-even transparent hole. The inner radius must be strictly smaller than the outer radius. A nonuniform semantic scale can turn the ring into an elliptical annulus.

procedure
(sector #:id id
[ #:center center
#:radius radius
#:start-angle start-angle
#:angle angle
#:rotation rotation
#:scale scale
#:opacity opacity
#:fill fill
#:stroke stroke
#:stroke-width stroke-width]) → path-visual?
  id : symbol?
  center : vec2? = origin
  radius : (and/c finite-real? positive?) = 1
  start-angle : finite-real? = 0
  angle : finite-real? = (/ pi 2)
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  fill : any/c = "cornflowerblue"
  stroke : any/c = "black"
  stroke-width : stroke-width? = 2

Creates the closed radial wedge from start-angle through the signed central angle. The sweep must be nonzero and no longer than a complete turn. A positive sweep is counter-clockwise.

procedure
(regular-polygon #:id id
[ #:center center
#:sides sides
#:radius radius
#:start-angle start-angle
#:rotation rotation
#:scale scale
#:opacity opacity
#:fill fill
#:stroke stroke
#:stroke-width stroke-width]) → path-visual?
  id : symbol?
  center : vec2? = origin
  sides : exact-integer? = 5
  radius : (and/c finite-real? positive?) = 1
  start-angle : finite-real? = (/ pi 2)
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  fill : any/c = "cornflowerblue"
  stroke : any/c = "black"
  stroke-width : stroke-width? = 2

Creates an equal-radius polygon with one vertex initially at start-angle. sides must be an exact integer at least three.

procedure
(star #:id id
[ #:center center
#:points points
#:outer-radius outer-radius
#:inner-radius inner-radius
#:start-angle start-angle
#:rotation rotation
#:scale scale
#:opacity opacity
#:fill fill
#:stroke stroke
#:stroke-width stroke-width]) → path-visual?
  id : symbol?
  center : vec2? = origin
  points : exact-integer? = 5
  outer-radius : (and/c finite-real? positive?) = 1
  inner-radius : (and/c finite-real? positive?) = 1/2
  start-angle : finite-real? = (/ pi 2)
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  fill : any/c = "gold"
  stroke : any/c = "black"
  stroke-width : stroke-width? = 2

Creates an alternating outer/inner regular star boundary. points must be at least two, and the inner radius must be strictly smaller than the outer radius.

procedure
(rounded-rectangle #:id id
[ #:center center
#:width width
#:height height
#:corner-radius corner-radius
#:rotation rotation
#:scale scale
#:opacity opacity
#:fill fill
#:stroke stroke
#:stroke-width stroke-width])
→ path-visual?
  id : symbol?
  center : vec2? = origin
  width : (and/c finite-real? positive?) = 2
  height : (and/c finite-real? positive?) = 1
  corner-radius : stroke-width? = 1/5
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  fill : any/c = "cornflowerblue"
  stroke : any/c = "black"
  stroke-width : stroke-width? = 2

Creates a rectangle with four cubic quarter-circle corners. Corner radius is nonnegative and may not exceed either half-extent. A zero radius creates the same outline topology as a sharp rectangle.

procedure
(arc-between-points start
end
#:id id
[ #:angle angle
#:opacity opacity
#:stroke stroke
#:stroke-width stroke-width]) → path-visual?
  start : vec2?
  end : vec2?
  id : symbol?
  angle : finite-real? = (/ pi 2)
  opacity : opacity? = 1
  stroke : any/c = "black"
  stroke-width : stroke-width? = 2

Creates the circular arc joining two distinct points with the specified signed central sweep. Its magnitude must be nonzero and strictly less than one full turn. Sign selects the side of the chord and traversal direction.

procedure
(curved-arrow start
end
#:id id
[ #:angle angle
#:opacity opacity
#:stroke stroke
#:stroke-width stroke-width
#:tip-length tip-length
#:tip-width tip-width]) → group-visual?
  start : vec2?
  end : vec2?
  id : symbol?
  angle : finite-real? = (/ pi 2)
  opacity : opacity? = 1
  stroke : any/c = "black"
  stroke-width : stroke-width? = 2
  tip-length : (and/c finite-real? positive?) = 3/10
  tip-width : (and/c finite-real? positive?) = 1/4

Creates a circular arc-between-points with a triangular tip aligned to its final tangent. The returned group has child identities formed from id plus -shaft and -tip.

procedure
(double-arrow start
end
#:id id
[ #:rotation rotation
#:scale scale
#:opacity opacity
#:stroke stroke
#:stroke-width stroke-width
#:tip-length tip-length
#:tip-width tip-width]) → arrow-visual?
  start : vec2?
  end : vec2?
  id : symbol?
  rotation : finite-real? = 0
  scale : scale-factor? = 1
  opacity : opacity? = 1
  stroke : any/c = "black"
  stroke-width : stroke-width? = 2
  tip-length : (and/c finite-real? positive?) = 3/10
  tip-width : (and/c finite-real? positive?) = 1/4

Creates the ordinary semantic arrow from start to end with both start-tip? and end-tip? enabled.

procedure
(labeled-point label
#:id id
[ #:center center
#:radius radius
#:label-offset label-offset
#:font-size font-size
#:font-family font-family
#:fill fill
#:stroke stroke
#:stroke-width stroke-width
#:color color
#:opacity opacity]) → group-visual?
  label : string?
  id : symbol?
  center : vec2? = origin
  radius : (and/c finite-real? positive?) = 1/10
  label-offset : vec2? = (vec2 1/4 1/4)
  font-size : (and/c finite-real? positive?) = 1/4
  font-family : any/c = 'roman
  fill : any/c = "crimson"
  stroke : any/c = "firebrick"
  stroke-width : stroke-width? = 2
  color : any/c = stroke
  opacity : opacity? = 1

Creates a dot and a plain-text label as one group. Its stable child identities are id plus -dot and -label; moving or fading the outer group therefore carries both together. Label placement is the explicit local label-offset, not a collision-aware layout operation.

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

58.1	Visual Protocols and Groups
58.2	Shapes and Path Visuals
58.3	Bitmap and SVG Visuals
58.4	Text Content and Layout
58.5	Semantic Text and Typography Styles
58.6	Numbers and Units
58.7	Matrices, Tables, and Vector Diagrams
58.8	Formula Construction and Layout
58.9	Formula Assemblies and Named Parts
58.10	Formula Source Selection and Matching
58.11	Arrows and Coordinate Axes
58.12	Live Endpoints and Mathematical Annotations
58.13	Complex and Polar Visuals
58.14	Function, Parametric, and Data Plots
58.15	Graph Helpers and Traced Paths
58.16	ODE Trajectories and Streamlines
58.17	Relations and Live Layout

58.2.1	Circle Visuals
58.2.2	Rectangle Visuals
58.2.3	Path Visuals
58.2.4	Mathematical Shape Catalogue