commit c2c72bff3aa029fefdf2bc829f9915a2c104d8f7
parent 6feeb1d5e33c26191abb74f7f4e3b717f805917b
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 19 May 2017 15:45:43 +0200
Convert the solstice CLI man page from ronn to asciidoc
Ronn seems quite deprecated; use the asciidoc format instead. Provide a
new build process based on the asciidoc tool suite to automatically
generate the TROFF and/or the HTML documentation from the asciidoc
files. Note that the solstice-input, solstice-output and
solstice-receiver man pages are not converted in asciidoc file, yet.
Diffstat:
5 files changed, 399 insertions(+), 245 deletions(-)
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
@@ -54,16 +54,10 @@ include_directories(
${Star3DUT_INCLUDE_DIR}
${CMAKE_CURRENT_BINARY_DIR})
-find_program(RONN ronn)
-if(NOT RONN)
- message(WARNING
- "The `ronn' program is missing. "
- "The solstice documentation cannot be generated.")
-endif()
-
################################################################################
# Build subprojects
################################################################################
+add_subdirectory(doc)
add_subdirectory(parser)
add_subdirectory(receivers)
@@ -81,33 +75,8 @@ set(SOLSTICE_ARGS_DEFAULT_IMG_SPP "1")
configure_file(${SOLSTICE_SOURCE_DIR}/solstice_args.h.in
${CMAKE_CURRENT_BINARY_DIR}/solstice_args.h @ONLY)
-
-################################################################################
-# Generate the documentation
-################################################################################
-if(RONN)
- configure_file(${SOLSTICE_SOURCE_DIR}/../doc/solstice.1.ronn.in
- ${CMAKE_CURRENT_BINARY_DIR}/solstice.1.ronn @ONLY)
-
- file(COPY
- ${SOLSTICE_SOURCE_DIR}/../doc/solstice-input.5.ronn
- ${SOLSTICE_SOURCE_DIR}/../doc/solstice-output.5.ronn
- ${SOLSTICE_SOURCE_DIR}/../doc/solstice-receiver.5.ronn
- DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
-
- set(SOLSTICE_MAN_PAGES
- solstice.1.ronn
- solstice-input.5.ronn
- solstice-output.5.ronn
- solstice-receiver.5.ronn)
- rcmake_prepend_path(SOLSTICE_MAN_PAGES ${CMAKE_CURRENT_BINARY_DIR})
-
- if(${CMAKE_HOST_UNIX})
- execute_process(COMMAND ${RONN} --style=man,toc ${SOLSTICE_MAN_PAGES})
- else()
- execute_process(COMMAND ${RONN} -5 --style=man,toc ${SOLSTICE_MAN_PAGES})
- endif()
-endif()
+configure_file(${SOLSTICE_SOURCE_DIR}/../doc/solstice.1.txt.in
+ ${CMAKE_CURRENT_BINARY_DIR}/doc/solstice.1.txt @ONLY)
################################################################################
# Configure and define targets
diff --git a/cmake/doc/CMakeLists.txt b/cmake/doc/CMakeLists.txt
@@ -0,0 +1,84 @@
+# Copyright (C) CNRS 2016-2017
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+cmake_minimum_required(VERSION 2.8)
+
+################################################################################
+# Look for asciidoc and a2x programs
+################################################################################
+find_program(ASCIIDOC asciidoc)
+set(SOLSTICE_DOC_DIR ${PROJECT_SOURCE_DIR}/../doc)
+
+if(NOT ASCIIDOC)
+ message(WARNING
+ "The `asciidoc' program is missing. "
+ "The solstice HTML documentation cannot be generated.")
+endif()
+
+if(CMAKE_HOST_UNIX)
+ find_program(A2X a2x)
+ if(NOT A2X)
+ message(WARNING
+ "The `a2x' program is missing. "
+ "The solstice man pages cannot be generated.")
+ endif()
+endif()
+
+################################################################################
+# Generate the TROFF man pages
+################################################################################
+set(MAN_TXT ${CMAKE_CURRENT_BINARY_DIR}/solstice.1.txt)
+
+if(A2X)
+ set(A2X_OPTS -dmanpage -fmanpage)
+
+ set(MAN_FILES)
+ foreach(_txt IN LISTS MAN_TXT)
+ add_custom_command(
+ OUTPUT ${_txt}.troff
+ COMMAND ${A2X} ${A2X_OPTS} ${_txt}
+ DEPENDS ${_txt}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Build troff man page ${_txt}"
+ VERBATIM)
+ list(APPEND MAN_FILES ${_txt}.troff)
+ endforeach()
+ add_custom_target(man-troff ALL DEPENDS ${MAN_FILES})
+endif()
+
+################################################################################
+# Generate the HTML documentation
+################################################################################
+if(ASCIIDOC)
+ set(ASCIIDOC_OPTS
+ -bxhtml11
+ -dmanpage
+ --attribute themedir=${SOLSTICE_DOC_DIR}
+ --theme=solstice-man)
+
+ set(MAN_FILES)
+ foreach(_txt IN LISTS MAN_TXT)
+ add_custom_command(
+ OUTPUT ${_txt}.html
+ COMMAND ${ASCIIDOC} ${ASCIIDOC_OPTS} ${_txt}
+ DEPENDS ${_txt}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Build HTML man page ${_txt}"
+ VERBATIM)
+ list(APPEND MAN_FILES ${_txt}.html)
+ endforeach()
+ add_custom_target(man-html ALL DEPENDS ${MAN_FILES})
+endif()
+
diff --git a/doc/solstice-man.css b/doc/solstice-man.css
@@ -0,0 +1,78 @@
+/* Copyright (C) CNRS 2016-2017
+ *
+ * This is free style sheet: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This CSS is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>. */
+
+body.manpage {
+ font-family:monospace;
+ font-size:2ex;
+ text-align: justify;
+ max-width: 55em;
+ margin: 1em;
+}
+
+body.manpage .monospaced, .literalblock {
+ margin: 2em;
+ color: #434241;
+}
+
+body.manpage em {
+ color: #660000
+}
+
+body.manpage div.verseblock > pre.content {
+ font-family: inherit;
+}
+
+body.manpage h1 {
+ padding-bottom: 0.5em;
+}
+body.manpage h2 {
+ border-style: none;
+}
+body.manpage div.sectionbody {
+ margin-left: 3em;
+}
+
+body.manpage #footer { display: none; }
+
+body.manpage div#toctitle { display: none; }
+
+body.manpage div#toc {
+ display.block ! important;
+ position:fixed;
+ top:0;
+ left:60em;
+ height:100%;
+ width: 100%;
+ padding:3em 0 0 0;
+ border-left:1px solid #dbdbdb;
+ background: #eeeeee
+}
+
+body.manpage div#toc a, div#toc a:link, div#toc a:visited {
+ display:block;
+ margin:0;
+ padding:0.33em 0.14em 0.33em 2em;
+ color:#999999;
+ text-decoration:none
+}
+
+body.manpage div#toc a:hover {
+ color:#666666;
+}
+
+@media print {
+ body.manpage div#toc { display: none; }
+}
+
diff --git a/doc/solstice.1.ronn.in b/doc/solstice.1.ronn.in
@@ -1,211 +0,0 @@
-solstice(1) -- compute the power collected by a concentrated solar plant
-=========================================================================
-
-## SYNOPSIS
-
-`solstice` [_option_]... [_file_]<br>
-`solstice` `-g` <_sub-option_[:...]> [_option_]... [_file_]<br>
-`solstice` `-p` <_sub-option_[:...]> [_option_]... [_file_]<br>
-`solstice` `-r` <_sub-option_[:...]> [_option_]... [_file_]<br>
-
-## DESCRIPTION
-
-`solstice` computes the total power collected by a concentrated solar plant, as
-described in the `solstice-input`(5) _file_. If the _file_ argument is not
-provided, the solar plant is read from standard input. To evaluate various
-efficiencies for each primary reflector, it computes losses due to cosine
-effect, shadowing and masking, orientation and surface irregularities,
-reflectivity and atmospheric transmission. The efficiency for each one of these
-effects is subsequently computed for each reflector.
-
-The entities on which computations must be performed are listed in the
-`solstice-receiver`(5) file submitted through the `-R` option. The estimated
-results follow the `solstice-output`(5) format and are written to the _output_
-file or to the standard output whether the `-o` _output_ option is defined or
-not, respectively. Note that the `solstice`'s algorithm is based on the
-Monte-Carlo method, which means that every result is provided with its
-numerical accuracy.
-
-`solstice` is designed to efficiently handle complex solar facilities: several
-reflectors can be specified (planes, conics, cylindro-parabolic, etc.) and
-positioned in 3D space, with a possibility for 1-axis and 2-axis
-auto-orientation. Multiple materials can be used, as long as the relevant
-physical properties are provided. Spectral effects are also taken into account:
-it is possible to define the spectral distribution of any physical property,
-including the input solar spectrum and the transmissivity of the atmosphere, at
-any spectral resolution. Refer to `solstice-input`(5) for more informations.
-
-In addition of the aforementioned computations, `solstice` provides three
-other functionalities. The `-g` option can be used to convert the
-`solstice-input`(5) geometries in CAO files. The `-p` option saves the sampled
-radiative paths used by the estimations, allowing to visualise them externally
-which may be a great help to identify a design issue. Finally, the `-r` option
-is used to render an image of the submitted solar facility. Note that these
-three options are mutually exclusives, and once defined, they replace the
-default `solstice` behaviour.
-
-## OPTIONS
-
-* `-D` <_azimuth_,_elevation_[:...]>:
- List of sun directions. A direction is defined by its _azimuthal_ and
- _elevation_ angles in degrees, with _azimuth_ in [0, 360[ and _elevation_ in
- [0, 90]. Each sun direction triggers a new computation whose results are
- concatenated to the _output_ file.
-
-* `-f`:
- Force overwrite of the _output_ file.
-
-* `-h`:
- List short help and exit.
-
-* `-g` <_sub-option_:...>:
- Generate the shape of the geometry defined in the submitted _file_ and store
- it in _output_. Available sub-options are:
-
- `format=obj`<br>
- Define the file format in which the meshes are stored. Currently, only the
- Alias Wavefront OBJ file format is supported.
-
- `split=<geometry|object|none>`<br>
- Define how the output mesh is split in sub meshes. A sub mesh can be
- generated for each `geometry` or for each `object` as defined in the
- `solstice-input`(5) file format. The `none` option means that only one
- mesh is generated for the whole solar facility. By default, the `split`
- option is set to `none`.
-
-* `-o` _output_:
- Write results to _output_ with respect to the `solstice-output`(5) format. If
- not defined, write results to standard output.
-
-* `-p` <_sub-option_:...>:
- Register the sampled radiative paths for each sun direction and write them to
- _output_. Available sub-options are:
-
- `default`<br>
- Use default sub-options configuration.
-
- `irlen=`_length_<br>
- Length of the radiative path segments going to the infinity. By default, it
- is computed relatively to the scene size.
-
- `srlen=`_length_<br>
- Length of the radiative path segments coming from the sun. By default, it is
- computed relatively to the scene size.
-
-* `-q`:
- Do not print the helper message when no _file_ is submitted.
-
-* `-n` _experiments-count_:
- Number of Monte-Carlo experiments used to estimate the solar flux. By
- default _experiments-count_ is set to @SOLSTICE_ARGS_DEFAULT_NREALISATIONS@.
-
-* `-r` <_sub-option_:...>:
- Render an image of the scene through a pinhole camera, for each submitted
- sun direction. Write the resulting images to _output_. Available sub-options
- are:
-
- `fov=`_angle_<br>
- Horizontal field of view of the camera in [30, 120] degrees. By default
- _angle_ is @SOLSTICE_ARGS_DEFAULT_CAMERA_FOV@ degrees.
-
- `img=`_width_`x`_height_<br>
- Definition of the rendered image in pixels. By default the image definition
- is @SOLSTICE_ARGS_DEFAULT_IMG_WIDTH@x@SOLSTICE_ARGS_DEFAULT_IMG_HEIGHT@.
-
- `pos=`_x_`,`_y_`,`_z_<br>
- Position of the camera. By default it is set to
- {@SOLSTICE_ARGS_DEFAULT_CAMERA_POS@} or it is automatically computed to
- ensure that the whole scene is visible, whether `tgt` is set or not,
- respectively.
-
- `rmode=<draft|pt>`<br>
- Rendering mode. In `draft` mode, images are computed by ray-casting; all
- materials are lambertian, the sun is ignored and the only light source is
- positioned at the camera position. In `pt` mode, the scene is rendered with
- the un-biased path-tracing Monte-Carlo algorithm; the materials described in
- the committed _file_ as well as the submitted sun directions are correctly
- handled and an uniform skydome is added to simulate the diffuse infinite
- lighting. By default `rmode` is set to `draft`.
-
- `spp=`_samples-count_<br>
- Number of samples per pixel. If `rmode` is `draft`, the samples position into
- a pixel are the same for all pixels. With `rmode=pt` the pixel samples are
- generated independently for each pixel. By default, use 1 sample per pixel.
-
- `tgt=`_x_`,`_y_`,`_z_<br>
- Position targeted by the camera. By default, it is set to
- {@SOLSTICE_ARGS_DEFAULT_CAMERA_TGT@} or it is automatically computed to
- ensure that the whole scene is visible, whether `pos` is set or not,
- respectively.
-
- `up=`_x_`,`_y_`,`_z_<br>
- Up vector of the camera. If `rmode` is `pt`, this vector also defines the
- direction toward the top of the skydome. By default, `up` is set to
- {@SOLSTICE_ARGS_DEFAULT_CAMERA_UP@}.
-
-* `-R` _receivers_:
- `solstice-receiver`(5) file defining the scene receivers, i.e. the solar
- plant entities for which `solstice` computes Monte-Carlo estimations.
-
-
-## EXAMPLES
-
-Launch `solstice` estimations for two sun directions whose azimuthal and
-elevation angles are {`45`,`70`} and {`50`,`75`}. The solar facility is
-described in `input.yaml` and the receivers on which the integrations must be
-performed are declared in the `rcvs.yaml` file. `10000` experiments are used
-by the Monte-Carlo estimations and the results are written to `output` even
-though this file already exists:
-
- $ solstice -D45,70:50,75 -R rcvs.yaml -n 10000 -f -o output input.yaml
-
-Generate a mesh for each geometry described in `input.yaml`, and save them in
-the `output` file with respect to the Alias Wavefront OBJ format. The meshes
-are positioned according to their orientation constraints, with respect to the
-sun direction whose azimuthal and elevation angles are {`30`,`60`}. Use the
-`csplit`(1) Unix command to generate an Alias Wavefront OBJ file per geometry
-stored in `output`. The name of the generated Alias Wavefront OBJ files are
-`geom<NUM>.obj` with `<NUM>` in [0, N-1] where N is the number of geometries
-described in `input.yaml`. Refer to `solstice-output`(5) for informations on
-the regular expression `^---$` used to split the output file:
-
- $ solstice -D30,60 -g format=obj:split=geometry -f -o output input.yaml
- $ csplit -f geom -b %02d.obj -z --suppress-matched output /^---$/ {*}
-
-Trace 100 radiative paths into the solar plant described in `input.yaml`, with
-respect to the sun direction whose azimuthal and elevations angles are `0` and
-`90` degrees, respectively. Write the `solstice-output`(5) result to the
-standard output and postprocess it with the `sed`(1) Unix command to remove the
-first line that stores the sun direction from which the radiative paths comes
-from. The remaining data that lists the radiative paths geometry are redirected
-into the `paths.vtk` file:
-
- $ solstice -n 100 -D0,90 -R rcvs.yaml -p default input.yaml | sed '1d' > paths.vtk
-
-Use the path-tracing rendering algorithm to draw the solar plant
-`solplant.yaml` with respect to the sun direction whose azimuthal and elevation
-angles are `180` and `45` degrees, respectively. Use `64` samples per pixel to
-estimate the per-pixel radiance and fix the up camera vector to {`0`,`0`,`1`}.
-Write the `solstice-output`(5) result to standard output and use the `sed`(1)
-Unix command to remove the first line which stores the sun direction used to
-draw the image. Finally, visualise the rendered picture by redirecting the
-remaining data to the `feh`(1) image viewer.
-
- $ solstice -D180,45 -r up=0,0,1:rmode=pt:spp=64 solplant.yaml | sed '1d' | feh -
-
-## COPYRIGHT
-
-`solstice` is copyright © CNRS 2016-2017. License GPLv3+: GNU GPL version
-3 or later <http://gnu.org/licenses/gpl.html>. This is a free software. You are
-free to change and redistribute it. There is NO WARRANTY, to the extent
-permitted by law.
-
-## SEE ALSO
-
-`csplit`(1),
-`feh`(1),
-`sed`(1),
-`solstice-input`(5),
-`solstice-output`(5),
-`solstice-receivers`(5)
-
diff --git a/doc/solstice.1.txt.in b/doc/solstice.1.txt.in
@@ -0,0 +1,234 @@
+// Copyright (C) CNRS 2016-2017
+//
+// This is free documentation: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This manual is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <http://www.gnu.org/licenses/>.
+:toc:
+
+solstice(1)
+===========
+
+NAME
+----
+solstice - compute the power collected by a concentrated solar plant
+
+SYNOPSIS
+--------
+[verse]
+*solstice*
+*solstice* [_option_]... [_file_]
+*solstice* *-g* <__sub-option__[:...]> [_option_]... [_file_]
+*solstice* *-p* <__sub-option__[:...]> [_option_]... [_file_]
+*solstice* *-r* <__sub-option__[:...]> [_option_]... [_file_]
+
+DESCRIPTION
+-----------
+*solstice* computes the total power collected by a concentrated solar plant, as
+described in the *solstice-input*(5) _file_. If the _file_ argument is not
+provided, the solar plant is read from standard input. To evaluate various
+efficiencies for each primary reflector, it computes losses due to cosine
+effect, shadowing and masking, orientation and surface irregularities,
+reflectivity and atmospheric transmission. The efficiency for each one of these
+effects is subsequently computed for each reflector.
+
+The entities on which computations must be performed are listed in the
+*solstice-receiver*(5) file submitted through the *-R* option. The estimated
+results follow the *solstice-output*(5) format and are written to the _output_
+file or to the standard output whether the *-o* _output_ option is defined or
+not, respectively. Note that the *solstice*'s algorithm is based on the
+Monte-Carlo method, which means that every result is provided with its
+numerical accuracy.
+
+*solstice* is designed to efficiently handle complex solar facilities: several
+reflectors can be specified (planes, conics, cylindro-parabolic, etc.) and
+positioned in 3D space, with a possibility for 1-axis and 2-axis
+auto-orientation. Multiple materials can be used, as long as the relevant
+physical properties are provided. Spectral effects are also taken into account:
+it is possible to define the spectral distribution of any physical property,
+including the input solar spectrum and the transmissivity of the atmosphere, at
+any spectral resolution. Refer to *solstice-input*(5) for more informations.
+
+In addition of the aforementioned computations, *solstice* provides three
+other functionalities. The *-g* option can be used to convert the
+*solstice-input*(5) geometries in CAO files. The *-p* option saves the sampled
+radiative paths used by the estimations, allowing to visualise them externally
+which may be a great help to identify a design issue. Finally, the *-r* option
+is used to render an image of the submitted solar facility. Note that these
+three options are mutually exclusives, and once defined, they replace the
+default *solstice* behaviour.
+
+OPTIONS
+-------
+*-D* <__azimuth__,__elevation__[:...]>::
+ List of sun directions. A direction is defined by its _azimuthal_ and
+ _elevation_ angles in degrees, with _azimuth_ in [0, 360[ and _elevation_ in
+ [0, 90]. Each sun direction triggers a new computation whose results are
+ concatenated to the _output_ file.
+
+*-f*::
+ Force overwrite of the _output_ file.
+
+*-h*::
+ List short help and exit.
+
+*-g* <__sub-option__:...>::
+ Generate the shape of the geometry defined in the submitted _file_ and store
+ it in _output_. Available sub-options are:
+
+ *format=obj*;;
+ Define the file format in which the meshes are stored. Currently, only the
+ Alias Wavefront OBJ file format is supported.
+
+ *split=*<**geometry**|*object*|*none*>;;
+ Define how the output mesh is split in sub meshes. A sub mesh can be
+ generated for each *geometry* or for each *object* as defined in the
+ *solstice-input*(5) file format. The *none* option means that only one
+ mesh is generated for the whole solar facility. By default, the *split*
+ option is set to *none*.
+
+*-o* _output_::
+ Write results to _output_ with respect to the *solstice-output*(5) format. If
+ not defined, write results to standard output.
+
+*-p* <__sub-option__:...>::
+ Register the sampled radiative paths for each sun direction and write them to
+ _output_. Available sub-options are:
+
+ *default*;;
+ Use default sub-options configuration.
+
+ **irlen=**_length_;;
+ Length of the radiative path segments going to the infinity. By default, it
+ is computed relatively to the scene size.
+
+ **srlen=**_length_;;
+ Length of the radiative path segments coming from the sun. By default, it
+ is computed relatively to the scene size.
+
+*-q*::
+ Do not print the helper message when no _file_ is submitted.
+
+*-n* _experiments-count_::
+ Number of Monte-Carlo experiments used to estimate the solar flux. By
+ default _experiments-count_ is set to @SOLSTICE_ARGS_DEFAULT_NREALISATIONS@.
+
+*-r* <__sub-option__:...>::
+ Render an image of the scene through a pinhole camera, for each submitted
+ sun direction. Write the resulting images to _output_. Available sub-options
+ are:
+
+ **fov=**_angle_;;
+ Horizontal field of view of the camera in [30, 120] degrees. By default
+ _angle_ is @SOLSTICE_ARGS_DEFAULT_CAMERA_FOV@ degrees.
+
+ **img=**_width_**x**_height_;;
+ Definition of the rendered image in pixels. By default the image definition
+ is @SOLSTICE_ARGS_DEFAULT_IMG_WIDTH@x@SOLSTICE_ARGS_DEFAULT_IMG_HEIGHT@.
+
+ **pos=**_x_**,**_y_**,**_z_;;
+ Position of the camera. By default it is set to
+ {@SOLSTICE_ARGS_DEFAULT_CAMERA_POS@} or it is automatically computed to
+ ensure that the whole scene is visible, whether *tgt* is set or not,
+ respectively.
+
+ **rmode=**<**draft**|**pt**>;;
+ Rendering mode. In *draft* mode, images are computed by ray-casting; all
+ materials are lambertian, the sun is ignored and the only light source is
+ positioned at the camera position. In *pt* mode, the scene is rendered with
+ the un-biased path-tracing Monte-Carlo algorithm; the materials described
+ in the committed _file_ as well as the submitted sun directions are
+ correctly handled and an uniform skydome is added to simulate the diffuse
+ infinite lighting. By default *rmode* is set to *draft*.
+
+ **spp=**_samples-count_;;
+ Number of samples per pixel. If *rmode* is *draft*, the samples position
+ into a pixel are the same for all pixels. With *rmode=pt* the pixel
+ samples are generated independently for each pixel. By default, use 1
+ sample per pixel.
+
+ **tgt=**_x_**,**_y_**,**_z_;;
+ Position targeted by the camera. By default, it is set to
+ {@SOLSTICE_ARGS_DEFAULT_CAMERA_TGT@} or it is automatically computed to
+ ensure that the whole scene is visible, whether *pos* is set or not,
+ respectively.
+
+ **up=**_x_**,**_y_**,**_z_;;
+ Up vector of the camera. If *rmode* is *pt*, this vector also defines the
+ direction toward the top of the skydome. By default, *up* is set to
+ {@SOLSTICE_ARGS_DEFAULT_CAMERA_UP@}.
+
+*-R* _receivers_::
+ *solstice-receiver*(5) file defining the scene receivers, i.e. the solar
+ plant entities for which *solstice* computes Monte-Carlo estimations.
+
+EXAMPLES
+--------
+
+Launch *solstice* estimations for two sun directions whose azimuthal and
+elevation angles are {*45*,*70*} and {*50*,*75*}. The solar facility is
+described in *input.yaml* and the receivers on which the integrations must be
+performed are declared in the *rcvs.yaml* file. *10000* experiments are used
+by the Monte-Carlo estimations and the results are written to *output* even
+though this file already exists:
+
+ $ solstice -D45,70:50,75 -R rcvs.yaml -n 10000 -f -o output input.yaml
+
+Generate a mesh for each geometry described in *input.yaml*, and save them in
+the *output* file with respect to the Alias Wavefront OBJ format. The meshes
+are positioned according to their orientation constraints, with respect to the
+sun direction whose azimuthal and elevation angles are {*30*,*60*}. Use the
+*csplit*(1) Unix command to generate an Alias Wavefront OBJ file per geometry
+stored in *output*. The name of the generated Alias Wavefront OBJ files are
+*geom*<__NUM__>**.obj** with __NUM__ in [0, N-1] where N is the number of
+geometries described in *input.yaml*. Refer to *solstice-output*(5) for
+informations on the regular expression *^---$* used to split the output file:
+
+ $ solstice -D30,60 -g format=obj:split=geometry -f -o output input.yaml
+ $ csplit -f geom -b %02d.obj -z --suppress-matched output /^---$/ {*}
+
+Trace 100 radiative paths into the solar plant described in *input.yaml*, with
+respect to the sun direction whose azimuthal and elevations angles are *0* and
+*90* degrees, respectively. Write the *solstice-output*(5) result to the
+standard output and postprocess it with the *sed*(1) Unix command to remove the
+first line that stores the sun direction from which the radiative paths comes
+from. The remaining data that lists the radiative paths geometry are redirected
+into the *paths.vtk* file:
+
+ $ solstice -n 100 -D0,90 -R rcvs.yaml -p default input.yaml | sed '1d' > paths.vtk
+
+Use the path-tracing rendering algorithm to draw the solar plant
+*solplant.yaml* with respect to the sun direction whose azimuthal and elevation
+angles are *180* and *45* degrees, respectively. Use *64* samples per pixel to
+estimate the per-pixel radiance and fix the up camera vector to {*0*,*0*,*1*}.
+Write the *solstice-output*(5) result to standard output and use the *sed*(1)
+Unix command to remove the first line which stores the sun direction used to
+draw the image. Finally, visualise the rendered picture by redirecting the
+remaining data to the *feh*(1) image viewer.
+
+ $ solstice -D180,45 -r up=0,0,1:rmode=pt:spp=64 solplant.yaml | sed '1d' | feh -
+
+COPYRIGHT
+---------
+*solstice* is copyright © CNRS 2016-2017. License GPLv3+: GNU GPL version
+3 or later <http://gnu.org/licenses/gpl.html>. This is a free software. You are
+free to change and redistribute it. There is NO WARRANTY, to the extent
+permitted by law.
+
+SEE ALSO
+--------
+*csplit*(1),
+*feh*(1),
+*sed*(1),
+*solstice-input*(5),
+*solstice-output*(5),
+*solstice-receivers*(5)
+
