#14 Documentation inconsistencies/incomplete specifications/missing format information

[Tim Holy]

• http://teem.sourceforge.net/nrrd/format.html#spaceunits suggests that "space units" is per-axis (there are dim, not spaceDim, components), yet example files like this one disagree. The latter is also consistent with unu make, suggesting the documentation is incorrect.

tim@diva:/tmp/nrrd$ teem-unu make -h -i dummy.raw -t uchar -s 3 3 3 2 -k space space space list -spc RAS -spu "mm" "mm" "mm" "none"
unu make: number of space units (4) not same as space dimension (3)
tim@diva:/tmp/nrrd$ teem-unu make -h -i dummy.raw -t uchar -s 3 3 3 2 -k space space space list -spc RAS -spu "mm" "mm" "mm"
<succeeds>

• The number of components in "space origin" is not specified
• If you're reading an image from a camera and a pixel has value 0xff (8-bit) or 0xffff (16-bit), it's obvious that pixel was saturated. But what if it's a 10-bit camera? In that case 0x03ff represents a saturated value, but I don't see any mechanism by which that can be encoded in the header. min and max concern the observed data, not the range that could be produced by the sensor.
• Similarly, particularly when the storage type is float or double, color images would benefit from knowing whether "white" corresponds to RGB(1.0,1.0,1.0) or RGB(255.0,255.0,255.0) (or some other choice).
• While one can specify a few color spaces (RGB, HSV, XYZ, and RGBA), grayscale is notably lacking. (It would indicate clearly that this is an image rather than some other kind of array.)
• The longstanding lack of a test suite is a disincentive for wide scale adoption and risks fragmentation of the format. While there are a few examples of headers on the website, very few of them exercise any of the more advanced functionality. At a minimum it would be good to prominently post a list of unu make commands generating many .nhdr files collectively spanning the functionality you'd like to "protect." This would solve the "read" problem. For the "write" problem, is there an equivalent of unu validate to check whether a given file is valid?

[Tim Holy]

To resolve some of the latter issues, in my own application I've added some special-casing "interpretation" to the space units field. Briefly, I allow one to specify the colorspace and whitepoint, where for grayscale "whitepoint" means the obvious thing (saturation of the sensor). Details are documented here.