commit c6dae44a14749fc44e639c52f2d37afc5f61c417
parent e4d069f508b7e3fd5266fe7b4d3a9b95292983a1
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 12 Nov 2018 16:18:45 +0100
Write man page of the htrdr-image file format
Diffstat:
3 files changed, 127 insertions(+), 4 deletions(-)
diff --git a/cmake/doc/CMakeLists.txt b/cmake/doc/CMakeLists.txt
@@ -13,6 +13,8 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
+set(HTRDR_DOC_DIR ${PROJECT_SOURCE_DIR}/../doc)
+
################################################################################
# Look for the a2x program
################################################################################
@@ -27,11 +29,24 @@ endif()
################################################################################
# Copy doc files
################################################################################
-configure_file(${HTRDR_SOURCE_DIR}/../doc/htrdr.1.txt.in
- ${CMAKE_CURRENT_BINARY_DIR}/htrdr.1.txt @ONLY)
+set(MAN_NAMES htrdr-image.5)
-add_custom_target(man-copy ALL) # TODO
+set(MAN_FILES)
+foreach(_name IN LISTS MAN_NAMES)
+ set(_src ${HTRDR_DOC_DIR}/${_name}.txt)
+ set(_dst ${CMAKE_CURRENT_BINARY_DIR}/${_name}.txt)
+ add_custom_command(
+ OUTPUT ${_dst}
+ COMMAND ${CMAKE_COMMAND} -E copy ${_src} ${_dst}
+ DEPENDS ${_src}
+ COMMENT "Copy the asciidoc ${_src}"
+ VERBATIM)
+ list(APPEND MAN_FILES ${_dst})
+endforeach()
+add_custom_target(man-copy ALL DEPENDS ${MAN_FILES})
+configure_file(${HTRDR_SOURCE_DIR}/../doc/htrdr.1.txt.in
+ ${CMAKE_CURRENT_BINARY_DIR}/htrdr.1.txt @ONLY)
list(APPEND MAN_NAMES htrdr.1)
################################################################################
diff --git a/doc/htrdr-image.5.txt b/doc/htrdr-image.5.txt
@@ -0,0 +1,108 @@
+// Copyright (C) 2018 CNRS, Université Paul Sabatier, |Meso|Star>
+//
+// 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:
+
+htrdr-image(5)
+==============
+
+NAME
+----
+htrdr-image - format of the images generated by htrdr(1)
+
+DESCRIPTION
+-----------
+The *htrdr-image* is a raw image file format whose data are stored in plain
+text. Characters after the '#' character are considered as comments and are
+thus ignore as well as empty lines. The first valid line stores 2 unsigned
+integers that represent the image definition, i.e. the number of pixels per
+line and per column. Then each line stores 3 pairs of floating points data,
+representing the pixel color encoded in the CIE 1931 XYZ color space. The
+first, second and third pair encodes the estimated radiance of the X, Y and Z
+pixel component, respectively. The first value of each pair is the radiance
+expected value while the second one is its associated standard deviation.
+
+Pixels are sorted line by line, with the origin defined as the top corner of
+the image. With an image definition of N by M pixels, with N the number of
+pixels per line and M the overall number of lines in the image. The first N
+pixels correspond to the pixels of the top line of the image, the following N
+pixels are the second line and so on.
+
+GRAMMAR
+-------
+
+[verse]
+-------
+<htrdr-image> ::= <definition>
+ <pixel>
+ [ <pixel> ... ]
+
+<definition> ::= <width> <height>
+<width> ::= INTEGER
+<height> ::= INTEGER
+
+<pixel> ::= <X> <Y> <Z>
+<X> ::= <estimate>
+<Y> ::= <estimate>
+<Z> ::= <estimate>
+
+<estimate> ::= <exoected-value> <standard-error>
+<expected-value> ::= REAL
+<standard-error> ::= REAL
+-------
+
+EXAMPLE
+-------
+The following output is emitted by *htrdr*(1) invoked to render an image whose
+definition is *800* by *600* pixels. Note that actually the comments or the
+blank lines are not necessaraly written as it by *htrdr*(1); they are are used
+here only to help in understanding the data layout. The comment after each
+pixel gives the two dimensionnal index of the pixel in the image: the first
+and second integer is the index of the line and the column of the pixel into
+the image, respectively.
+
+[verse]
+------
+800 600 # Image definition
+
+# Pixels of the 1st line
+0.0002559 2.90278e-05 0.0003754 4.48780e-05 0.0003200 3.16818e-05 # (1,1)
+0.0002956 3.37333e-05 0.0003395 4.16836e-05 0.0003384 4.60855e-05 # (2,1)
+0.0003761 5.43206e-05 0.0003130 3.48458e-05 0.0003380 3.32255e-05 # (3,1)
+ ...
+0.0007135 0.000114694 0.0007661 0.000135251 0.0007978 0.000126122 # (799,1)
+0.0006591 0.000114968 0.0007473 0.000141289 0.0004398 7.33230e-05 # (800,1)
+
+# Pixels of the 2nd line
+0.0003330 6.02808e-05 0.0004218 7.66163e-05 0.0003446 3.81472e-05 # (1,2)
+0.0003504 4.93154e-05 0.0003232 2.52040e-05 0.0003036 2.42803e-05 # (2,2)
+0.0002720 4.69853e-05 0.0003413 4.12614e-05 0.0002525 2.06930e-05 # (3,2)
+ ...
+0.0007528 0.000131807 0.0008919 0.000184047 0.0005487 0.000130065 # (799,2)
+0.0006822 0.000142027 0.0006618 7.85956e-05 0.0004443 5.99220e-05 # (800,2)
+
+ ...
+
+# Pixels of the 600^th line
+0.0002697 7.44208e-05 0.0002310 2.56492e-05 0.0001958 2.30952e-05 # (1,600)
+0.0004325 0.000125897 0.0002222 2.22320e-05 0.0002047 2.60948e-05 # (2,600)
+0.0002782 5.81477e-05 0.0002756 4.99110e-05 0.0002172 3.30041e-05 # (3,600)
+ ...
+0.0003548 4.32117e-05 0.0003070 3.80437e-05 0.0002387 2.49820e-05 # (799,600)
+0.0003078 2.61915e-05 0.0004609 0.000113663 0.0002699 4.29776e-05 # (800,600)
+------
+
+SEE ALSO
+--------
+*htrdr*(1)
diff --git a/doc/htrdr.1.txt.in b/doc/htrdr.1.txt.in
@@ -255,5 +255,5 @@ NO WARRANTY, to the extent permitted by law.
SEE ALSO
--------
-*csplit*(1), *htpp*(1), *mpirun*(1), *htcp*(5), *htmie*(5), *htrdr-image*(5)
+*csplit*(1), *mpirun*(1), *htcp*(5), *htmie*(5), *htrdr-image*(5)
