3 Shape Attributes

3 Shape Attributes🔗ℹ

Every occupied point in 3D space has associated attributes. The attributes that Pict3D manages, which influence rendering, are reflected color, emitted color, and material.

procedure
(current-color) → RGBA
(current-color c) → Void
  c : RGBA
= default-color
procedure
(current-emitted) → Emitted
(current-emitted e) → Void
  e : Emitted
= default-emitted
procedure
(current-material) → Material
(current-material m) → Void
  m : Material
= default-material

New Pict3D instances set their shapes’ attributes using the values of these parameters.

Example:

> (parameterize ([current-color (rgba "chocolate")])
(sphere origin 1/2))

syntax
(with-color c body ...)

   rgba : RGBA
syntax
(with-emitted e body ...)

   emitted : Emitted
syntax
(with-material m body ...)

   material : Material

Equivalent to (parameterize ([current-color c]) body ...), etc.

value
default-color : RGBA = (rgba "white")
value
default-emitted : Emitted = (emitted "black" 0)
value
default-material : Material
=
(material #:ambient 0.05
          #:diffuse 0.6
          #:specular 0.35
          #:roughness 0.3)

Default values of current-color, current-emitted and current-material.

procedure
(set-color p c) → Pict3D
  p : Pict3D
  c : RGBA
procedure
(set-emitted p e) → Pict3D
  p : Pict3D
  e : Emitted
procedure
(set-material p m) → Pict3D
  p : Pict3D
  m : Material

Return new Pict3D instances with the attributes of every shape changed.

Example:

> (set-emitted
   (parameterize ([current-color  (rgba "chocolate")])
     (sphere origin 1/2))
   (emitted "lightgreen" 2))

In large scenes, especially in scenes created using freeze, these operations can be time-consuming. Prefer using with-color, with-emitted and with-material. If you must use these functions, use them with replace-group and replace-in-group.

3.1 Reflected Color Attributes🔗ℹ

type
RGBA
predicate
rgba? : (-> Any Boolean : RGBA)

The type and predicate of reflected colors with optional transparency.

procedure
(rgba color [alpha]) → RGBA
   color :
(U RGBA
   Real
   (Listof Real) (Vectorof Real) FlVector
   String (Instance Color%))
  alpha : Real = 1
(rgba red green blue [alpha]) → RGBA
  red : Real
  green : Real
  blue : Real
  alpha : Real = 1

Constructs an RGBA value from its components, or converts a color in another representation to an RGBA. If color already has an alpha component, it is multiplied by alpha in the result.

Examples:

> (rgba "white")
(rgba 1.0 1.0 1.0 1.0)
> (rgba "white" 0.5)
(rgba 1.0 1.0 1.0 0.5)
> (rgba (rgba "white") 0.5)
(rgba 1.0 1.0 1.0 0.5)
> (rgba 1/2)
(rgba 0.5 0.5 0.5 1.0)
> (rgba 0.2 0.3 0.4)
(rgba 0.2 0.3 0.4 1.0)
> (rgba '(1/2 1/4 1/8))
(rgba 0.5 0.25 0.125 1.0)
> (rgba #(1/2 1/4 1/8))
(rgba 0.5 0.25 0.125 1.0)
> (rgba (flvector 0.5 0.25 0.125))
(rgba 0.5 0.25 0.125 1.0)

All component values are converted to flonums and clamped to the range [0,1].

procedure
(rgba-red rgba) → Flonum
  rgba : RGBA
procedure
(rgba-green rgba) → Flonum
  rgba : RGBA
procedure
(rgba-blue rgba) → Flonum
  rgba : RGBA
procedure
(rgba-alpha rgba) → Flonum
  rgba : RGBA

Return the components of rgba.

You’ll usually want to use match or match-define instead:

> (match-define (rgba r g b a) (rgba "lavender" 0.75))
> (list r g b a)
'(0.9019607843137255 0.9019607843137255 0.9803921568627451 0.75)

3.2 Emitted Color Attributes🔗ℹ

type
Emitted
predicate
emitted? : (-> Any Boolean : Emitted)

The type and predicate of emitted colors, which include red, green, blue and intensity components.

procedure
(emitted color [intensity]) → Emitted
   color :
(U Emitted
   Real
   (Listof Real) (Vectorof Real) FlVector
   String (Instance Color%))
  intensity : Real = 1
(emitted red green blue [intensity]) → Emitted
  red : Real
  green : Real
  blue : Real
  intensity : Real = 1

Constructs an Emitted value from its components, or converts a color in another representation to an Emitted. If color already has a fourth component, it is multiplied by intensity in the result.

All component values are converted to flonums, set to 0.0 if negative, and normalized so that the largest of red, green and blue is 1.0.

Examples:

> (emitted "blue")
(emitted 0.0 0.0 1.0 1.0)
> (emitted "darkblue")
(emitted 0.0 0.0 1.0 0.5450980392156862)

procedure
(emitted-red emitted) → Flonum
  emitted : Emitted
procedure
(emitted-green emitted) → Flonum
  emitted : Emitted
procedure
(emitted-blue emitted) → Flonum
  emitted : Emitted
procedure
(emitted-intensity emitted) → Flonum
  emitted : Emitted

Return the components of emitted.

You’ll usually want to use match or match-define instead:

> (match-define (emitted r g b i) (emitted 1 2 3 1))
> (list r g b i)
'(0.3333333333333333 0.6666666666666666 1.0 3.0)

3.3 Material Attributes🔗ℹ

type
Material
predicate
material? : (-> Any Boolean : Material)

The type and predicate of materials, which include ambient, specular, diffuse, and roughness components.

procedure
(material [ #:ambient ambient
#:diffuse diffuse
#:specular specular
#:roughness roughness]) → Material
  ambient : Real = 0
  diffuse : Real = 0
  specular : Real = 0
  roughness : Real = 0.1

Contructs a material from its components. For realistic-looking materials, ambient, diffuse and specular should sum to 1 (but this is not enforced).

Example:

> (combine
   (with-material (material #:ambient  1.0) (sphere (pos 1 0 0) 1/2))
   (with-material (material #:diffuse  1.0) (sphere (pos 0 1 0) 1/2))
   (with-material (material #:specular 1.0) (sphere (pos 0 0 1) 1/2)))

The x-axis sphere has only ambient reflectance. It reflects an imaginary white light in all directions with the same intensity.

The y-axis sphere has only diffuse reflectance. It looks dull; not shiny at all.

The z-axis sphere has only specular reflectance. It looks only shiny.

The roughness component affects only specular reflectance. Generally, the less rough the sphere, the shinier it looks.

Example:

> (combine
   (with-material (material #:specular 1.0 #:roughness 0.1)
     (sphere (pos 1 0 0) 1/2))
   (with-material (material #:specular 1.0 #:roughness 0.2)
     (sphere (pos 0 1 0) 1/2))
   (with-material (material #:specular 1.0 #:roughness 0.4)
     (sphere (pos 0 0 1) 1/2)))

procedure
(material-ambient material) → Flonum
  material : Material
procedure
(material-diffuse material) → Flonum
  material : Material
procedure
(material-specular material) → Flonum
  material : Material
procedure
(material-roughness material) → Flonum
  material : Material

Return the components of material.

3.4 Vertex Attributes🔗ℹ

The functions triangle and quad accept not just position arguments, but vertex arguments that contain positions and can override any current shape attributes.

Examples:

> (define (make-a-vertex dv)
    (match-define (dir r g b) dv)
    (vertex (pos+ origin dv 0.5)
            #:normal (if (<= (- r g) 0) dv #f)
            #:color (rgba (* 0.5 (+ 1 r))
                          (* 0.5 (+ 1 g))
                          (* 0.5 (+ 1 b)))
            #:emitted (if (> b 0.9) (emitted 1 2) #f)))
> (combine
   (for*/list ([ρ  (in-range -90 91 10)]
               [θ  (in-range -180 180 10)])
     (define last-ρ (- ρ 10))
     (define last-θ (- θ 10))
     (define dvs (list (angles->dir θ ρ)
                       (angles->dir last-θ ρ)
                       (angles->dir last-θ last-ρ)
                       (angles->dir θ last-ρ)))
     (apply quad (map make-a-vertex dvs))))

type
Vertex
predicate
vertex? : (-> Any Boolean : Vertex)

The type and predicate of vertex data.

procedure
(vertex pos
[ #:normal normal
#:color color
#:emitted emitted
#:material material]) → Vertex
  pos : Pos
  normal : (U #f Dir) = #f
  color : (U #f RGBA) = #f
  emitted : (U #f Emitted) = #f
  material : (U #f Material) = #f

Constructs data for one vertex. When normal is omitted or #f, the normal is computed using vertex positions. (See triangle and quad.) For any other attribute, omission or #f indicates that the attribute should have the value of current-color, current-emitted or current-material.

procedure
(vertex-pos vertex) → Pos
  vertex : Vertex
procedure
(vertex-normal vertex) → (U #f Dir)
  vertex : Vertex
procedure
(vertex-color vertex) → (U #f RGBA)
  vertex : Vertex
procedure
(vertex-emitted vertex) → (U #f Emitted)
  vertex : Vertex
procedure
(vertex-material vertex) → (U #f Material)
  vertex : Vertex

Return the attributes of vertex.

3.5 Interval Arguments🔗ℹ

type
Interval
predicate
interval? : (-> Any Boolean : Interval)

The type and predicate of closed intervals.

procedure
(interval min max) → Interval
min : Real
max : Real

Constructs an Interval value from its endpoints. Endpoints may be given in either order and are converted to flonums.

Examples:

> (interval 0 -1)
(interval -1.0 0.0)
> (interval -inf.0 +inf.0)
(interval -inf.0 +inf.0)

value
zero-interval : Interval = (interval 0 0)
value
unit-interval : Interval = (interval 0 1)

Common intervals.

procedure
(interval-min i) → Flonum
i : Interval
procedure
(interval-max i) → Flonum
i : Interval

Return the endpoints of i.

You’ll usually want to use match or match-define instead:

> (match-define (interval mn mx) (interval 1 -1))
> (list mn mx)
'(-1.0 1.0)

3.6 Arc Arguments🔗ℹ

type
Arc
predicate
arc? : (-> Any Boolean : Arc)

The type and predicate of closed arcs.

procedure
(arc start end) → Arc
start : Real
end : Real

Constructs an Arc value from its start and end angles. Angles are converted to flonums and normalized so that start is in [0,360) and end is no less than start.

Examples:

> (arc 0 0)
(arc 0.0 0.0)
> (arc 0 360)
(arc 0.0 360.0)
> (arc -90 90)
(arc 270.0 450.0)
> (arc 90 -90)
(arc 90.0 270.0)
> (arc 0 450)
(arc 0.0 90.0)

value
zero-arc : Arc = (arc 0 0)
value
circle-arc : Arc = (arc 0 360)

Common arcs.

procedure
(arc-start a) → Flonum
a : Arc
procedure
(arc-end a) → Flonum
a : Arc

Return the start and end angles of a.

You’ll usually want to use match or match-define instead:

> (match-define (arc start end) (arc 360 0))
> (list start end)
'(0.0 360.0)

1	Quick Start
2	Constructors
3	Shape Attributes
4	Position and Direction Vectors
5	Combining Scenes
6	Transformation
7	Deformation and Tessellation
8	Collision Detection
9	Rendering
10	3D Universe

3.1	Reflected Color Attributes
3.2	Emitted Color Attributes
3.3	Material Attributes
3.4	Vertex Attributes
3.5	Interval Arguments
3.6	Arc Arguments