commit 772cbdb48cbb6f314c915a2a84519bfaf45461eb
parent 181555ef1710cac7abd7e36ebc1133bfc2caca4f
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 11 May 2017 15:39:27 +0200
Minor rewriting of the solstice-input man
Diffstat:
1 file changed, 70 insertions(+), 71 deletions(-)
diff --git a/doc/solstice-input.5.ronn b/doc/solstice-input.5.ronn
@@ -263,16 +263,16 @@ into the `solstice-input`(5) file but is provided by the `solstice`(1) command.
This allows to use the same unmodified `solstice-input`(5) file for several
simulations with different sun directions.
-The main `sun` property is its direct normal irradiance or `dni`. Its value is
+The main `sun` property is its direct normal irradiance, or `dni`. Its value is
a scalar defining the average direct normal irradiance of the sun on its whole
spectrum. The optional `spectrum` parameter describes the per wavelength
distribution of the sun `dni`. Note that this distribution is automatically
-normalized by `solstice`(1). If the `spectrum` attribute is not defined, use
-the default smarts295 spectrum instead [TODO-ref].
+normalized by `solstice`(1). If the `spectrum` attribute is not defined,
+`solstice`(1) uses the default smarts295 spectrum instead [TODO-ref].
-Finally, the `rad-ang-distrib` parameter controls the radial angular
-distribution of the sun directions. If not defined, the sun directions are
-assumed to be parallels. The available radial angular distributions are:
+The `rad-ang-distrib` parameter controls the radial angular distribution of the
+sun directions. If it is not defined, the sun directions are assumed to be
+parallels. The available radial angular distributions are:
* `pillbox`:
TODO
@@ -310,8 +310,8 @@ The available material descriptors are:
with n1 and n2 the indices of refraction of the incident and transmitted
media, and wi and wt the incident and transmitted direction. Note that the
- `solstice-input` file must ensure that the description of the scene media is
- consistent; a ray travelling in a medium _A_ can only encounter a medium
+ `solstice-input`(5) file must ensure that the description of the scene media
+ is consistent; a ray travelling in a medium _A_ can only encounter a medium
interface whose `medium_i` attribute is _A_. The default medium is assumed to
be the vacuum, i.e. its refractive index is 1 and its absorptivity is 0.
@@ -355,13 +355,13 @@ The available material descriptors are:
All the material descriptors, excepted the `virtual`, provide an optional
`normal-map` attribute that defines a path toward a Portable PixMap image [2]
-whose each pixel stores a normal expressed in the tangent space of the
-interface. By default the un-perturbated 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 the shape. For the `hemisphere`, `hyperbol`, `parabol`, `plane`
-and `parabolic-cylinder` shapes, the image is mapped in the {X,Y} plane. The
-other shapes are not parameterized and consequently, applying a normal-mapped
+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 the shape. For the `hemisphere`, `hyperbol`, `parabol`, `plane` and
+`parabolic-cylinder` shapes, the image is mapped in the {X,Y} plane. The other
+shapes are not parameterized and consequently, applying a normal-mapped
material on these shapes leads to undefined behaviors.
## SHAPE
@@ -377,13 +377,13 @@ surfaces.
### Quadric
A quadric shape is defined from a quadric equation and a set of 2D clipping
-operations listed by its `clip` parameter performed in their {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 in a triangular
-mesh with respect to the quadric discretization parameters. This mesh is used
-by `solstice`(1) as a "proxy" to speed up the access toward the quadric shape:
-the quadric position and its associated normal are in fine computed from the
-quadric equation.
+operations performed in their {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 in a triangular mesh with respect to the
+discretisation parameters of the quadric. This mesh is used by `solstice`(1)
+as a "proxy" to speed up the access toward the quadric shape: the quadric
+position and its associated normal are in fine computed from the quadric
+equation.
The quadric surface is parameterized in the {X,Y} plane. Its parameterization
domain is defined from the bounds of its clipped mesh in the {X,Y} plane:
@@ -392,8 +392,8 @@ domain is defined from the bounds of its clipped mesh in the {X,Y} plane:
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 mesh along the X and Y axis.
+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 axis.
The available quadrics are:
@@ -405,7 +405,7 @@ The available quadrics are:
x\^2 + y\^2 + (z-`radius`)\^2 = `radius`\^2
* `hyperbol`:
- Hyperbolic quadric defines along the Z axis whose minimum is positioned at
+ Hyperbolic quadric defined along the Z axis whose minimum is positioned at
the origin. The `slices` parameter controls the discretisation of the
hyperbol. If not defined, it is automatically computed with respect to the
hyperbol curvature.
@@ -419,7 +419,7 @@ The available quadrics are:
f = `focals.real` / g
* `parabol`:
- Parabolic quadric defines along the Z axis whose minimum is positioned at the
+ Parabolic quadric defined along the Z axis whose minimum is positioned at the
origin. The `slices` parameter controls the discretisation of the parabol. If
not defined, it is automatically computed with respect to the parabol
curvature.
@@ -428,7 +428,7 @@ The available quadrics are:
* `parabolic-cylinder`:
Parabolic cylinder oriented along the Z axis whose main axis is along the X
- axis and minimum is positionned at the origin. The `slices` parameter
+ axis and minimum is positioned at the origin. The `slices` parameter
controls the discretisation of the parabolic cylinder. If not defined, it is
automatically computed with respect to the parabolic cylinder curvature.
@@ -444,7 +444,7 @@ A clipping operation, or `polyclip`, is used to remove some 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` and `SUB` clip operands,
remove the quadric surface that intersects or does not intersect the
-`contour-descriptor`, respectively. The available `countour-descriptor`s are:
+`contour-descriptor`, respectively. The available `countour-descriptors` are:
* `circle-descriptor`:
Circular contour whose size is defined by the `radius` parameter. Actually,
@@ -452,21 +452,21 @@ remove the quadric surface that intersects or does not intersect the
attribute that defines the overall number of segments used to approximate the
circle.
-* `vertices-descriptor`:
- Polygonal contour describes by a list of 2D vertices. The polygon edges are
- defined by connecting each vertex to its previous one. To ensure that the
- polygon is closed, the first and the last vertex is automatically connected.
- Note that `solstice`(1) assumes that the defined polygon does not overlap
- itself, i.e. their non consecutive edges are not intersecting.
+* `vertices-descriptor`: Polygonal contour describes by a list of 2D vertices.
+ The polygon edges are defined by connecting each vertex to its previous one.
+ To ensure that the polygon is closed, an additional edge is automatically
+ created between the first and the last vertex. Note that `solstice`(1)
+ assumes that the defined polygon does not overlap itself, i.e. their non
+ consecutive edges are not intersecting.
The `clip` parameter of the quadrics lists a set of the aforementioned 2D
-`polyclip`. Each of these clipping operation is successively applied on the
+`polyclips`. Each of these clipping operation is successively applied on the
remaining quadric surface, in the order on which they are declared. For
-instance, the following example defines 5 clipping operations on a plane to
-describe a rectangle with a circular hole at each of its corner. The first
-`polyclip` limits the infinite plane to a rectangle centered in 0 whose
-size in X and Y is 8 and 4, respectively. The 4 subsequent `polyclips` drill
-the rectangle near of its corner with circles whose radius is 0.5:
+instance, the following example uses 5 clipping operations on a plane to build
+a rectangle with a circular hole at each of its corner. The first `polyclip`
+limits the infinite plane to a rectangle centered in 0 whose size in X and Y is
+8 and 4, respectively. The 4 subsequent `polyclips` drill the
+rectangle near of its corner with circles whose radius is 0.5:
plane:
clip:
@@ -479,37 +479,37 @@ the rectangle near of its corner with circles whose radius is 0.5:
### Triangular mesh
Triangular meshes are generated by `solstice`(1) from a shape description or
-loaded from a CAO file. Note that the mesh normals are defined per triangle.
-They are thus discontinuous even for smooth shapes as spheres. The triangular
-meshes are not parameterized, i.e. they do not provide a mapping from a 3D
-position onto its surface to a 2D coordinates. Applying a normal-mapped
-material to a triangular meshes will thus produce undefined behaviors.
+loaded from a CAO file. Their normals are defined per triangle and are thus
+discontinuous even for smooth shapes as spheres. The triangular meshes are not
+parameterized, i.e. they do not provide a mapping from a 3D position onto its
+surface to a 2D coordinates. Applying a normal-mapped material to a triangular
+meshes will thus produce undefined behaviors.
The available triangular meshes are:
* `cuboid`:
- Axis aligned cuboid centered in 0 whose dimensions along the 3 axis are
- defined by the `size` parameter. The front side of the cuboid surface looks
- outside the cuboid shape.
+ Axis aligned cuboid centered in 0 whose corner positions and dimensions along
+ the 3 axis are defined by the `size` parameter. The front side of the cuboid
+ surface looks outside the cuboid.
* `cylinder`:
Cylinder centered in 0 whose `height` is along the positive Z axis. The top
and the bottom of the cylinder is capped. The `stacks` and `slices`
parameters control the discretisation, i.e. the number of divisions, along or
around the Z axis, respectively. The front side of the cylinder surface looks
- outside the cylinder shape.
+ outside the cylinder.
* `sphere`:
Triangulated sphere centered in 0. The `stacks` and `slices` parameters
control the discretisation, i.e. the number of divisions, along or around the
Z axis, respectively. The front side of the sphere surface looks outside the
- sphere shape.
+ sphere.
* `stl`:
Path toward an external mesh file defined with respect to the `ST`ereo
`L`ithography file format. The front side of the loaded triangles is defined
- with respect to their vertex ordering: a triangle is front facing when their
- vertices are clock wise ordered.
+ with respect to their vertex ordering into the STL file: a triangle is front
+ facing when their vertices are clock wise ordered.
## ENTITY
@@ -539,19 +539,19 @@ its ancestors with its own name. This naming convention is used in the
- name: level2
An entity encapsulates either a `geometry` or a `pivot`. The former is a
-collection of `objects` i.e. `shapes` with their associated `material` and an
+collection of `objects`, i.e. `shapes` with their associated `material` and an
optional `transformation`. The latter is used to control the dynamic
positioning of the child entities with respect to some constraints defined by
the pivot type, and the sun directions submitted by `solstice`(1). Each entity
can also have a list of `anchors`. An anchor is used to define a position
relative to the entity into which it is declared.
-For geometric entity one have to define if the encapsulated geometry is
-`primary`, i.e. it is directly lit by the sun and it is used to concentrate the
-solar flux as, for instance, a primary mirror. One can define all the solar
-plant geometric entity as primary but a well designed solar plant where only
-primary mirrors are tagged as primary will drastically reduce the convergence
-speed of the `solstice`(1) simulations.
+For geometric entity one have to define if the encapsulated geometry is a
+`primary` geometry, i.e. a geometry directly lit by the sun and used to
+concentrate the solar flux (e.g. a primary mirror). One can define all the
+solar plant geometric entities as primaries but a well designed solar plant
+with correctly tagged primary geometries will drastically improve the
+convergence speed of the `solstice`(1) simulations.
### Template
@@ -588,9 +588,9 @@ An `anchor` defines a relative position into the entity hierarchy. They are
particularly useful for pivots and hyperbolic shapes that may have to reference
a position relative to an entity whose transformations may also depends of its
ancestor. An anchor has a `name` that must be unique for the whole sets of per
-entity anchors. An anchor is identified into the solar plant by concatenating, with
-the '.' character, the `entity-identifier` of the entity into which it is
-declared with its own name. For instance, in the following example, the
+entity anchors. An anchor is identified into the solar plant by concatenating,
+with the '.' character, its name to the `entity-identifier` of the entity into
+which it is declared. For instance, in the following example, the
`anchor-identifier` of the anchor named `anchor0` is `level0.level1.anchor0`:
entity:
@@ -622,21 +622,21 @@ following example, the entities `entity0.level0.level1` and
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` can be applied to a `geometry` or an `entity` to move them in
-space. Its `rotation` parameter list 3 angles in degrees defining the rotation
-to perform around the X, Y and Z axis. The `translation` attribute describes
-the offsets to apply along the X, Y and Z axis. Let the local repair `p` of an
-geometry, `p` is transformed in `p'` with respect to its associated `transform`
-as follow:
+A `transform` is used to move an `object` or an `entity` in space. The
+`rotation` parameter list 3 angles in degrees defining the rotation to perform
+around the X, Y and Z axis. The `translation` attribute describes the offsets
+to apply along the X, Y and Z axis. Let the local repair `p` of an object, `p`
+is transformed in `p'` with respect to its associated `transform` as follow:
p' = Rx * Ry * Rz * (T + p)
-with `T` the `translation` vector and `Rx`, `Ry` and `Rz` the rotation matrices
+with `T` the translation vector and `Rx`, `Ry` and `Rz` the rotation matrices
around the X, Y and Z axis defined as:
| 1 0 0 | | cY 0 sY | | cZ -sZ 0 |
@@ -644,8 +644,7 @@ around the X, Y and Z axis defined as:
| 0 sX cX | |-sY 0 cY | | 0 0 1 |
where `c<X|Y|Z>` and `s<X|Y|Z>` are the cosine and the sinus, respectively, of
-the rotation angles around the `X`, `Y` and `Z` axis defined by the `rotation`
-vector.
+the rotation angles around the X, Y and Z axis.
## EXAMPLE
