Material descriptors

The available material descriptors are:

dielectric

Interface between two dielectric media. Its medium_i parameter defines the current medium (the medium the ray travels in), while medium_t represents the opposite medium. Incoming rays are either specularly reflected or refracted according to a Fresnel term:

Fr = 1/2 * (Rs^2 + Rp^2)

with Rs and Rp the reflectance for light polarized with its electric field perpendicular or parallel to the plane of incidence, respectively:

Rs = (n1 * |wi.N| - n2 * |wt.N|) / (n1 * |wi.N| + n2 * |wt.N|)
Rp = (n2 * |wi.N| - n1 * |wt.N|) / (n2 * |wi.N| + n1 * |wt.N|)

with n1 and n2 the indices of refraction of the incident and transmitted media, and wi and wt the incident and transmitted direction.

Be careful to ensure media consistency in the solstice-input file: a ray travelling in a medium A can only encounter a medium interface whose medium_i attribute is A. Consequently, a dielectric material must be defined as a double-sided material whose front and back interfaces are dielectrics with inverted media:

material:
  front:
    dielectric:
      medium_i: &vacuum { refractive_index: 1, extinction: 0 }
      medium_t: &glass { refractive_index: 1.5, extinction: 20 }
  back:
    dielectric:
      medium_i: *glass
      medium_t: *vacuum

If media consistency is not ensured, solstice(1) will fail to run simulations. Note that by default, the surrounding medium is assumed to be vacuum, i.e. its refractive index and extinction are scalars with values 1 and 0, respectively. If an atmosphere is defined, the refractive index of the surrounding medium is still the scalar 1 but its extinction is that of the atmosphere.

matte

Diffuse surface. Reflects the same intensity in all directions independently of the incoming direction.

mirror

Specular or glossy reflection, depending on whether the slope_error parameter is 0 or not. Glossy reflections are controlled by a microfacet BRDF. The microfacet normals are distributed according to the Beckmann or Pillbox distribution, as specified by the normal-distrib attribute.

Let S be the slope_error parameter in ]0, 1]. The Beckmann distribution is defined as:

D(wh) = exp(-tan^2(a) / m^2) / (PI * m^2 * cos^4(a))

with a = arccos(wh.N) and m = sqrt(2)*S, while the Pillbox distribution is defined as:

        | 0;                         if |wh.N| >= S
D(wh) = |
        | 1 / (PI * (1 - cos^2(S))); if |wh.N| < S

thin-dielectric

The interface is assumed to be a thin slab of a dielectric material. The medium_i parameter defines the outside dielectric medium while medium_t is the medium of the thin slab. Incoming rays are either specularly reflected or transmitted (without deviation) according to a Fresnel term (see dielectric above for the formula). The underlying scattering function correctly handles the multiple refraction effects within the thin slab.

The same media consistency rules as for dielectric apply: if not ensured, solstice(1) will fail to run simulations. By default, the surrounding medium is vacuum (refractive index 1, extinction 0). If an atmosphere is defined, the refractive index of the surrounding medium is still 1, but its extinction is that of the atmosphere.

virtual

Fully transparent interface.

Normal map

All material descriptors except virtual provide an optional normal-map attribute that defines a path to a Portable PixMap image (see the NOTES, section, reference 5) whose pixels store a normal expressed in the tangent space of the interface. By default, the unperturbed tangent space normal is {0,0,1}. The PPM image can be encoded on 8 or 16 bits per component either in ASCII or binary. The parameterization of this 2D image onto the shape surfaces depends on the type of shape. For the hemisphere, hyperbol, parabol, plane and parabolic-cylinder shapes, the image is mapped in the {X,Y} plane. Other shapes are not parameterized; applying a normal-mapped material to them leads to undefined behaviour.

Quadric

A quadric shape is defined from a quadric equation and a set of 2D clipping operations performed in its {X,Y} plane. By convention, the front side of the quadric surface looks toward the positive Z axis. Internally, the clipped quadric surface is discretized into a triangular mesh according to the quadric's discretization parameters. This mesh is used by solstice(1) as a proxy to speed up access to the quadric shape; the exact position and normal are ultimately computed from the quadric equation.

The quadric surface is parameterized in the {X,Y} plane:

u = (x - lowerX) / (upperX - lowerX)
v = (y - lowerY) / (upperY - lowerY)

with u and v the mapped 2D coordinates from a 3D position {x,y,z} onto the quadric, and lower<X|Y> and upper<X|Y> the lower and upper bounds of the clipped quadric along the X and Y axes. The available quadrics are:

hemisphere

Hemispheric shape defined along the Z axis whose minimum is at the origin. The slices parameter controls the number of divisions along the Z axis.

x^2 + y^2 + (z-radius)^2 = radius^2

hyperbol

Hyperbolic quadric defined along the Z axis whose minimum is at the origin. The slices parameter controls the discretization of the hyperbol. If not defined, it is automatically computed from the hyperbol curvature.

(x^2 + y^2) / a^2 - (z + z0 - g/2)^2 / b^2 + 1 = 0

a^2 = g^2(f - f^2)
b = g(f - 1/2)
z0 = |b| + g/2
g = focals.real + focals.image
f = focals.real / g

parabol

Parabolic quadric defined along the Z axis whose minimum is at the origin. The slices parameter controls the discretization of the parabol. If not defined, it is automatically computed from the parabol curvature.

x^2 + y^2 - 4 * focal * z = 0

parabolic-cylinder

Parabolic cylinder oriented along the Z axis, with its main axis along the X axis and minimum at the origin. The slices parameter controls the discretization. If not defined, it is automatically computed from the curvature.

y^2 - 4 * focal * z = 0

plane

Plane whose normal points along the positive Z axis. The slices attribute controls the discretization of the clipped plane.

Clipping

A clipping operation, or polyclip, removes parts of the quadric surface. It is defined by a 2D contour-descriptor expressed in the {X,Y} plane and a clipping operation. The AND operand retains the portion of the quadric that intersects the contour; the SUB operand removes the portion that intersects the contour. The available contour descriptors are:

circle-descriptor

Circular contour whose size is defined by the radius parameter. solstice(1) discretizes the circular contour using the segments attribute as the number of segments used to approximate the circle.

vertices-descriptor

Polygonal contour described by a list of 2D vertices. Polygon edges connect each vertex to its predecessor; an additional edge automatically closes the polygon between the last and first vertex. Note that solstice(1) assumes the polygon does not self-intersect.

The clip parameter of a quadric lists a set of polyclips applied successively in declaration order. For example, the following uses 5 clipping operations on a plane to build a rectangle with a circular hole at each corner:

plane:
  clip:
  - {operation: AND, vertices: [[-4,-2],[-4,2],[4,2],[4,-2]]}
  - {operation: SUB, circle: {radius: 0.5, center: [-3,-1]}}
  - {operation: SUB, circle: {radius: 0.5, center: [-3, 1]}}
  - {operation: SUB, circle: {radius: 0.5, center: [ 3,-1]}}
  - {operation: SUB, circle: {radius: 0.5, center: [ 3, 1]}}

Triangular mesh

Triangular meshes are generated by solstice(1) from a shape description or loaded from a CAO file. Their normals are defined per triangle and are thus discontinuous even for smooth shapes. Triangular meshes are not parameterized; applying a normal-mapped material to them produces undefined behaviour. The available triangular meshes are:

cuboid

Axis-aligned cuboid centered at the origin, whose corner positions and dimensions along the three axes are defined by the size parameter. The front side of the surface looks outside the cuboid.

cylinder

Cylinder centered at the origin whose height is along the positive Z axis. Top and bottom are capped. The stacks and slices parameters control the number of divisions along and around the Z axis, respectively. The front side looks outside the cylinder.

sphere

Triangulated sphere centered at the origin. The stacks and slices parameters control the number of divisions along and around the Z axis, respectively. The front side looks outside the sphere.

stl

Path to an external mesh file in ASCII STereoLithography (STL) format. The front side of each triangle is determined by the vertex ordering in the STL file: a triangle is front-facing when its vertices are clockwise-ordered.

Template

A template is a first-level entity with no existence in the solar plant itself. It is used to pre-declare an entity hierarchy that can then be instantiated multiple times by referencing it through common entities with YAML data tagging:

- template: &my-template
    name: bar
    primary: 1
    geometry: ...
- entity:
    name: foo0
    transform: {translation: [-10.5, 0, 0]}
    children: [*my-template]
- entity:
    name: foo1
    transform: {translation: [0, 0, 0]}
    children: [*my-template]
- entity:
    name: foo2
    transform: {translation: [10.5, 0, 0]}
    children: [*my-template]

Pivot

A pivot is a special kind of node that automatically orients its child geometry according to the sun position and pivot parameters. It is typically (but not mandatorily) the parent of a reflector that, once pivoted, will redirect sun light toward a target. A pivot cannot be the child of another pivot.

The target parameter is the most important pivot parameter. Four types of target are available:

position

The target is an absolute point in world coordinates.

anchor

The target is a position relative to an entity (see the ANCHOR section).

sun

The target is the center of the sun.

direction

The pivot reflects light in the given direction, specified in world coordinates.

Pivots can also have an optional ref_point parameter defining a 3D point in the coordinate system of the pivot's children that is used by the pointing algorithm. If not provided, it defaults to the origin.

Two flavours of pivot are available:

x_pivot

Single-axis pivot rotating around the +X axis in its local coordinate system. Its pointing algorithm considers an incoming ray from the center of the sun and rotates its children so that a specular reflection at ref_point using +Z as the local normal hits the target, or produces the specified direction.

zx_pivot

Two-axis pivot: first a rotation around the +Z axis in its local coordinate system, then a rotation around the +X axis in the resulting coordinate system. The optional spacing parameter defines a translation along the +Y axis applied after the first rotation (default: 0). Its pointing algorithm considers an incoming ray from the center of the sun and rotates its children so that a specular reflection at ref_point using +Y as the local normal hits the target, or produces the specified direction.

Anchor

An anchor defines a relative position in the entity hierarchy. Anchors are particularly useful for pivots and hyperbolic shapes that must reference a position relative to an entity whose transformation may depend on its ancestors. An anchor's name must be unique among all anchors in its entity and cannot contain dots, spaces or tabulations. An anchor is identified in the solar plant by concatenating its name to the entity-identifier of the entity in which it is declared, using ‘.’ as separator. For example, the identifier of an anchor named anchor0 declared in level0.level1 is level0.level1.anchor0.

When the root entity name of a template is unknown (because the template has not yet been instantiated), the self reserved keyword can be used to reference the unknown root entity. For example:

- template: &my-template
    name: level0
    anchor: [{name: anchor0, position: [1, 2, 3]}]
    child:
    - name: level1
      pivot:
        x_pivot:
          ref_point: {0, 0, 0}
          target: {anchor: self.level0.anchor0}

- entity: {name: entity0, child: [*my-template]}
- entity: {name: entity1, child: [*my-template]}

Transform

A transform moves an object or an entity in space. The rotation parameter lists 3 angles in degrees defining rotations around the X, Y and Z axes. The translation attribute describes offsets along the X, Y and Z axes. Given a local frame p of an object, p is transformed into p' as:

p' = Rx * Ry * Rz * (T + p)

with T the translation vector and Rx, Ry, Rz the rotation matrices around the X, Y and Z axes:

     | 1  0   0 |        | cY  0 sY |        | cZ -sZ  0 |
Rx = | 0 cX -sX |;  Ry = |  0  1  0 |;  Rz = | sZ  cZ  0 |
     | 0 sX  cX |        |-sY  0 cY |        |  0   0  1 |

where c<X|Y|Z> and s<X|Y|Z> are the cosine and sine of the rotation angles around the X, Y and Z axes, respectively.