commit e4e5ca1dc7a5415badc590b2ea15780f8ce2d3d1
parent 60e038197906c1802a90473009d5cf985d21a3f6
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 15 Nov 2018 11:44:13 +0100
Write the htpp man page
Diffstat:
3 files changed, 157 insertions(+), 3 deletions(-)
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
@@ -65,6 +65,29 @@ set_target_properties(htpp PROPERTIES
SOVERSION ${VERSION_MAJOR})
################################################################################
+# Man pages
+###############################################################################
+find_program(A2X NAMES a2x a2x.py)
+if(NOT A2X)
+ message(WARNING
+ "The `a2x' program is missing. "
+ "The htpp man pages cannot be generated.")
+else()
+ set(_src ${PROJECT_SOURCE_DIR}/../doc/htpp.1.txt)
+ set(_txt ${CMAKE_CURRENT_BINARY_DIR}/htpp.1.txt)
+ add_custom_command(
+ OUTPUT htpp.1
+ COMMAND ${CMAKE_COMMAND} -E copy ${_src} ${_txt}
+ COMMAND ${A2X} -dmanpage -fmanpage ${_txt}
+ DEPENDS ${_src}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Buid ROFF man page htpp.1"
+ VERBATIM)
+ add_custom_target(man-roff ALL DEPENDS htpp.1)
+ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/htpp.1 DESTINATION share/man/man1)
+endif()
+
+################################################################################
# Define output & install directories
################################################################################
install(TARGETS htpp
diff --git a/doc/htpp.1.txt b/doc/htpp.1.txt
@@ -0,0 +1,132 @@
+// Copyright (C) 2018 CNRS, |Meso|Star>, 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
+// 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/>.
+:toc:
+
+htpp(1)
+=======
+
+NAME
+----
+htpp - High-Tune: Post Process
+
+SYNOPSIS
+--------
+[verse]
+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* tone maps the high dynamic range colors of the _input_ image with the
+following filmic tone mapping operator [2]:
+
+ out-color = f(in-color) / white-scale * exposure
+
+with:
+
+ f(x) = (x * (A*x + C*B) + D*E) / (x*(A*x + B + D*F)) - E/F
+
+ A = 0.15
+ B = 0.50
+ C = 0.10
+ D = 0.20
+ 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 color
+space. Finally, the resulting pixel components are clamped to [0, 1] and
+encoded on 8-bits.
+
+OPTIONS
+-------
+*-e* _exposure_::
+ Pixel exposure. By default its value is 1.
+
+*-f*::
+ Force overwrite of the _output_ file.
+
+*-h*::
+ List short help and exit.
+
+*-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 they were regular
+ colors but no XYZ to sRGB conversion is applied on the tone mapped values.
+
+*-t* _threads-count_::
+ Hint on the number of threads to use. By default use as many threads as CPU
+ cores.
+
+*-v*::
+ Make *htpp* verbose.
+
+*-w _white-scale_*::
+ Factor used to normalize input colors. If not defined, _white-scale_ is
+ automatically computed from the luminance of the _input_ image.
+
+*--version*::
+ Display version information and exit.
+
+EXAMPLES
+--------
+
+Post process the *htrdr-image*(5) saved in *img.htrdr* and write the resulting
+PPM image in *img.ppm*. Use the *-f* option to overwrite *img.ppm* if it
+already exists:
+
+ $ htpp -f -o img.ppm img.htrdr
+
+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 -
+
+Use the *-u* option to visualise the uncertainty of the *img.htrdr* image
+rather than its estimated radiance:
+
+ $ htpp -u 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/>
+
+COPYRIGHT
+---------
+*htpp* is copyright © 2018 CNRS, |Meso|Star> <contact@meso-star.com>,
+Université Paul Sabatier <contact-edstar@laplace.univ-tlse.fr>. License
+GPLv3+: GNU GPL version 3 or later <https://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
+--------
+*feh*(1),
+*htrdr-image*(5)
diff --git a/src/htpp.c b/src/htpp.c
@@ -84,9 +84,8 @@ print_help(const char* cmd)
printf(
" -v make the program verbose.\n");
printf(
-" -w WHITE-SCALE white scale factor used to normalize input colors.\n"
-" By the white scale factor is automatically computed from\n"
-" the luminance of the submitted colors\n");
+" -w WHITE-SCALE Factor used to normalize input colors. By default, it is\n"
+" automatically computed from the luminance of the INPUT image.\n");
printf(
" --version display version information and exit.\n");
printf("\n");
