commit 7691f195a7ff3404147593fd9e906c7fa6e76700
parent f0de42eac75a283c04f96d3b1c1ded22b29cf90c
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 25 Mar 2020 17:36:29 +0100
Update the man page
Diffstat:
2 files changed, 71 insertions(+), 36 deletions(-)
diff --git a/doc/htpp.1.txt b/doc/htpp.1.txt
@@ -1,4 +1,5 @@
-// Copyright (C) 2018-2019 CNRS, |Meso|Star>, Université Paul Sabatier
+// Copyright (C) 2018, 2019, 2020 |Meso|Star> (contact@meso-star.com)
+// Copyright (C) 2018, 2019 CNRS, Université Paul Sabatier
//
// 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
@@ -28,12 +29,16 @@ htpp [_option_] ... [_input_]
DESCRIPTION
-----------
-*htpp* post-processes an *htrdr-image*(5) and convert it to a regular
-PPM image [1]. If _input_ is not defined, the *htrdr-image*(5) is read from
-standard input.
+*htpp* post-processes a *htrdr-image*(5) and convert it to a regular PPM image
+[1]. If _input_ is not defined, the *htrdr-image*(5) is read from standard
+input. Two post-processing procedures are provided: the post-processing of the
+image colors (option *-i*), and the mapping of a given pixel component onto a
+color ramp (option "*-m*). By default, *htpp* post-process the image color.
-*htpp* tone maps the high dynamic range colors of the _input_ image with the
-following filmic tone mapping operator [2]:
+To post-process the image colors (option *-i*) *htpp* assumes that the first,
+the third and the fifth component of each *htrdr-image*(5) pixel encodes a
+color with respect to the CIE 1931 XYZ color space. *htpp* first
+tone maps these colors with the following filmic tone mapping operator [2]:
out-color = f(in-color * exposure) / f(white-scale)
@@ -48,41 +53,69 @@ with:
E = 0.02
F = 0.30
-The _exposure_ term is an user defined parameter provided by the *-e* option.
-If not defined, a default _exposure_ of 1 is used. The _white-scale_ factor is
-either defined by the user through the *-w* option or automatically computed
-as the luminance from which roughly all image pixels have a luminance less
-than _white-scale_. Currently, *htpp* empirically defines _white-scale_ as the
-luminance greater than the luminance of 99.5% of the pixels. Once tone mapped,
-the pixels are transformed from the CIE 1931 XYZ color space to the sRGB
-linear color space before to be gamma corrected. Finally, the resulting pixel
-components are clamped to [0, 1] and encoded on 8-bits.
+The _exposure_ term is an user defined parameter provided as the _exposure_
+image option. If not defined, a default _exposure_ of 1 is used. The
+_white-scale_ factor is either defined by the user through the _white_ image
+option or automatically computed as the luminance from which roughly all image
+pixels have a luminance less than _white-scale_. Currently, *htpp* empirically
+defines _white-scale_ as the luminance greater than the luminance of 99.5% of
+the pixels. Once tone mapped, the pixels are transformed from the CIE 1931 XYZ
+color space to the sRGB linear color space before to be gamma corrected.
+Finally, the resulting pixel components are clamped to [0, 1] and encoded on
+8-bits.
+
+The mapping of a pixel component onto a color ramp is controlled by the *-m*
+option. The pixel component to post-process is defined by the _pixcpnt_
+mapping option. *htpp* first defines the range of the component onto the whole
+image, eventually clamped to the _range_ mapping option. The component is then
+normalized according to this range and then mapped to a built-in color ramp
+whose name is defined by the _palette_ mapping option.
OPTIONS
-------
-*-e* _exposure_::
- Pixel exposure. By default its value is 1.
-
*-f*::
Force overwrite of the _output_ file.
*-h*::
List short help and exit.
+*-i* <__sub-option__>[:<__sub-option__> ...]::
+ Post-process the color of the *htrdr-image*(5). The first, the third and the
+ fifth pixel component are assumed to store the pixel color encoded into the
+ CIE 1931 XYZ color space. Available sub-options are:
+
+ **default**;;
+ Use the default values of the sub-options.
+
+ **exposure**=__real__;;
+ Pixel exposure. By default its value is 1.
+
+ **white**=__white-scale__;;
+ Factor used to normalize input colors. If not defined, the white scale is
+ automatically computed from the luminance of the _input_ image.
+
+*-m* <__sub-option__>[:<__sub-option__> ...]::
+ Map a pixel component to a regular color. Available sub options are:
+
+ **default**;;
+ Use the default values of the sub-options.
+
+ **palette**=__palette-name__;;
+ Color palette to use. Available palettes are the ones supported
+ by the Star-ColorMap library [3]. The default palette is inferno.
+
+ **pixcpnt**=__pixel-component__;;
+ Index in [0, 7] of the pixel component to map. The default pixel component
+ is the first one, i.e. *pixcpnt*=0.
+
+ **range**=__min__,__max__;;
+ Range to clamp the values of the pixel component. By default the range is
+ infinite.
+
*-o* _output_::
File where the PPM image is written. If not defined, write _output_ to
standard output.
-*-u*::
- Generate an image of the uncertainties of the pixels rather of their
- estimated radiance. The uncertainties are tone mapped as if they were
- regular colors but no XYZ to sRGB conversion is applied on the tone mapped
- values.
-
-*-T*::
- Generate an image of the per radiative path computation time rather than an
- image of the estimated radiance.
-
*-t* _threads-count_::
Hint on the number of threads to use. By default use as many threads as CPU
cores.
@@ -110,24 +143,26 @@ Convert *img.htrdr* and visualise the resulting image by redirecting the
standard output to the *feh*(1) image viewer. Use an _exposure_ of *0.5* and
explicitly define the normalization factor to *0.0025*:
- $ htpp -e 0.5 -w 0.0025 img.htrdr | feh -
+ $ htpp -i exposure=0.5:white=0.0025 img.htrdr | feh -
-Use the *-u* option to visualise the uncertainty of the *img.htrdr* image
-rather than its estimated radiance:
+Use the *-m* option to map the values of the second pixel component clamped in
+[0, 2] to the color ramp _magma_.
- $ htpp -u img.htrdr | feh -
+ $ htpp -m pixcpnt=1:palette=magma:range=0 img.htrdr | feh -
NOTES
-----
1. Portable PixMap - <http://netpbm.sourceforge.net/doc/ppm.html>
2. Filmic tone mapping operator -
<http://filmicworlds.com/blog/filmic-tonemapping-operators/>
+3. Star-ColorMap - <https://gitlab.com/meso-star/star-cmap>
COPYRIGHT
---------
-Copyright © 2018-2019 CNRS, |Meso|Star> <contact@meso-star.com>,
-Université Paul Sabatier <contact-edstar@laplace.univ-tlse.fr>. *htpp* is free
-software released under the GPLv3+ license: GNU GPL version 3 or later
+Copyright © 2018, 2019, 2020 |Meso|Star> <contact@meso-star.com>.
+Copyright © 2018, 2019 CNRS, Université Paul Sabatier
+<contact-edstar@laplace.univ-tlse.fr>. *htpp* is free software released under
+the GPLv3+ license: GNU GPL version 3 or later
<https://gnu.org/licenses/gpl.html>. You are free to change and redistribute
it. There is NO WARRANTY, to the extent permitted by law.
diff --git a/src/htpp.c b/src/htpp.c
@@ -125,7 +125,7 @@ print_help(const char* cmd)
printf(
" -i <image-option>[:<image-option> ... ]\n"
" handle the input as an image whose first, third,\n"
-" and fourth pixel component store the pixel color in\n"
+" and fifth pixel component store the pixel color in\n"
" the CIE 1931 XYZ color space\n");
printf(
" -m <map-option>[:<map-option> ... ]\n"
