9.3
58.13 Complex and Polar Visuals
Complex and polar helpers convert ordinary numeric values into semantic points or Visuals. Plane constructors create static group trees; complex transformation requests map sampled world geometry. The individual contracts state the accepted domains and discontinuity policies.
See also Arrows and Coordinate Axes, Function, Parametric, and Data Plots.
58.13.1 Complex and Polar Coordinates
Complex-coordinate operations use ordinary Racket complex numbers and convert only at the drawing boundary. Polar-coordinate operations follow the same approach for polar values and paths. Both planes are normal immutable group trees, not special scene types.
procedure
(complex->point value) → vec2?
value : complex?
procedure
(point->complex point) → complex?
point : vec2?
Returns the ordinary Racket complex number whose real and imaginary parts are
the x and y components of point.
Complex components and point coordinates round-trip without a renderer.
Example:
> (point->complex (complex->point 3+4i)) 3+4i
procedure
(complex-domain-color value [ #:saturation saturation #:brightness brightness #:radial? radial?]) → rgba-color? value : complex? saturation : (real-in 0 1) = 3/4 brightness : (real-in 0 1) = 4/5 radial? : boolean? = #t
Returns an opaque semantic colour whose hue is the argument of value.
When #:radial? is true, its brightness also increases smoothly with
the modulus. This is a pure colour helper; it does not create a renderer-only
pixel effect.
procedure
(complex-domain-coloring function #:id id [ #:x-min x-min #:x-max x-max #:y-min y-min #:y-max y-max #:columns columns #:rows rows #:saturation saturation #:brightness brightness #:radial? radial? #:opacity opacity]) → group-visual? function : (procedure-arity-includes/c 1) id : symbol? x-min : finite-real? = -3 x-max : finite-real? = 3 y-min : finite-real? = -2 y-max : finite-real? = 2 columns : exact-positive-integer? = 24 rows : exact-positive-integer? = 16 saturation : (real-in 0 1) = 3/4 brightness : (real-in 0 1) = 4/5 radial? : boolean? = #t opacity : (real-in 0 1) = 1
Samples function once at the centre of each rectangular complex cell
and returns a normal group of coloured rectangle Visuals. The function must
return finite complex values. Each cell has a stable name derived from
id, so the result remains ordinary semantic scene content rather than
a continuous raster shader.
procedure
(complex-plane #:id id [ #:x-range x-range #:y-range y-range #:x-length x-length #:y-length y-length #:center center #:rotation rotation #:scale scale #:grid? grid? #:labels? labels? #:grid-stroke grid-stroke #:grid-stroke-width grid-stroke-width #:axes-stroke axes-stroke #:axes-stroke-width axes-stroke-width #:label-font-size label-font-size #:label-color label-color]) → group-visual? id : symbol? x-range : axis-range? = (axis-range -4 4 1) y-range : axis-range? = (axis-range -3 3 1) x-length : (and/c finite-real? positive?) = 8 y-length : (and/c finite-real? positive?) = 6 center : vec2? = origin rotation : finite-real? = 0 scale : scale-factor? = 1 grid? : boolean? = #t labels? : boolean? = #t grid-stroke : any/c = "lightsteelblue" grid-stroke-width : (and/c finite-real? (>=/c 0)) = 1 axes-stroke : any/c = "navy" axes-stroke-width : (and/c finite-real? (>=/c 0)) = 2 label-font-size : (and/c finite-real? positive?) = 1/4 label-color : any/c = "navy"
Builds a Cartesian complex plane. Its direct 'coordinates child is a
number-plane tree; when #:labels? is true, direct
'real-axis and 'imaginary-axis text leaves label Re and Im.
The numeric labels are static construction-time labels.
procedure
(apply-complex-function target function [ #:samples samples #:adaptive? adaptive? #:tolerance tolerance #:max-depth max-depth #:discontinuities discontinuities]) → apply-pointwise-request? target : (or/c visual? symbol? visual-path?) function : (procedure-arity-includes/c 1) samples : exact-positive-integer? = 24 adaptive? : boolean? = #t tolerance : (and/c finite-real? positive?) = 1/32 max-depth : exact-nonnegative-integer? = 8 discontinuities : (or/c 'split 'error) = 'error
Creates apply-pointwise with each sampled world point converted by
point->complex, passed to function, then converted back with
complex->point. The function must return a complex number with finite
real and imaginary parts at every retained sampled point. The default strict
'error discontinuity policy makes an accidental bad function result
fail visibly. Use 'split for an intentional pole or excluded domain:
failed samples then break the path rather than adding a long connecting chord.
This API does not infer branch cuts or normalize by an axes’ numeric coordinate
scale.
procedure
(apply-complex-homotopy target homotopy [ #:samples samples #:adaptive? adaptive? #:tolerance tolerance #:max-depth max-depth #:discontinuities discontinuities]) → apply-homotopy-request? target : (or/c visual? symbol? visual-path?) homotopy : (procedure-arity-includes/c 2) samples : exact-positive-integer? = 24 adaptive? : boolean? = #t tolerance : (and/c finite-real? positive?) = 1/32 max-depth : exact-nonnegative-integer? = 8 discontinuities : (or/c 'split 'error) = 'error
Creates apply-homotopy with each source point converted by
point->complex, passed together with the current local phase to
homotopy, and converted back with complex->point. The
homotopy must return a finite complex value at every retained sample. Its
strict default discontinuity policy matches apply-complex-function;
choose 'split for an intentional pole or excluded domain.
procedure
(polar-coordinate? value) → boolean?
value : any/c
Recognizes an immutable reading returned by point->polar.
procedure
(polar-coordinate-radius value) → (and/c finite-real? (>=/c 0))
value : polar-coordinate?
Returns the nonnegative radius of a polar reading.
procedure
(polar-coordinate-angle value) → finite-real?
value : polar-coordinate?
Returns the angle of a polar reading in radians.
procedure
(polar->point radius angle) → vec2?
radius : finite-real? angle : finite-real?
Returns (vec2 (* radius (cos angle)) (* radius (sin angle))). A
signed radius is accepted, which lets polar-graph express conventional
rose curves.
procedure
(point->polar point) → polar-coordinate?
point : vec2?
Returns a nonnegative-radius reading. The angle uses atan’s interval
[-pi, pi]; the origin is assigned angle zero.
procedure
(polar-plane #:id id [ #:radii radii #:angles angles #:center center #:rotation rotation #:scale scale #:labels? labels? #:stroke stroke #:stroke-width stroke-width #:grid-stroke grid-stroke #:grid-stroke-width grid-stroke-width #:label-font-size label-font-size #:label-color label-color]) → group-visual? id : symbol? radii : (listof (and/c finite-real? positive?)) = '(1 2 3) angles : (listof finite-real?) = (list 0 (/ pi 4) (/ pi 2)) center : vec2? = origin rotation : finite-real? = 0 scale : (and/c finite-real? positive?) = 1 labels? : boolean? = #t stroke : any/c = "steelblue" stroke-width : (and/c finite-real? (>=/c 0)) = 2 grid-stroke : any/c = "lightsteelblue" grid-stroke-width : (and/c finite-real? (>=/c 0)) = 1 label-font-size : (and/c finite-real? positive?) = 1/4 label-color : any/c = "navy"
Builds a static polar grid. Its direct children are named 'rings and
'rays, plus 'labels when requested. Ring children use
ring-0, ring-1, and so on; ray children use ray-0, ray-1,
and so on. Labels are deliberately static and may overlap for dense choices.
procedure
(polar-graph radius-function #:id id [ #:start start #:end end #:samples samples #:center center #:rotation rotation #:scale scale #:opacity opacity #:stroke stroke #:stroke-width stroke-width #:fill fill]) → path-visual? radius-function : (procedure-arity-includes/c 1) id : symbol? start : finite-real? = 0 end : finite-real? = (* 2 pi) samples : (and/c exact-integer? (>=/c 2)) = 240 center : vec2? = origin rotation : finite-real? = 0 scale : scale-factor? = 1 opacity : opacity? = 1 stroke : any/c = "crimson" stroke-width : (and/c finite-real? (>=/c 0)) = 3 fill : any/c = #f
Evenly samples (radius-function theta) from start through
end and returns an ordinary open path. Each result must be a finite
real, but it may be negative. Sampling is uniform in angle, not adaptive or
arc-length parameterized.