XISF Version 1.0 Specification (DRAFT 9.1)

8.3.1 Plain Text Serialization of Decimal Integers

A serialization of a decimal (base 10) integer value as plain text shall satisfy the following regular expression:^[21]

Examples:

8.3.2 Plain Text Serialization of Binary, Octal and Hexadecimal Integers

Serializations of binary (base 2), octal (base 8) and hexadecimal (base 16) integer values as plain text shall satisfy the following regular expressions:^[21]

Binary:

Octal:

Hexadecimal:

Examples:

In the first example, 10100111100101₂ = 10725₁₀.

In the second example, 570261₈ = 192689₁₀.

In the third example, if the represented value is a two's complement signed 32-bit integer, the value is 80E950AB₁₆ = –2132193109₁₀. However, if the represented value is an unsigned integer, the value is 2162774187₁₀.

8.3.3 Plain Text Serialization of Floating Point Values

A serialization of a numeric floating point scalar as plain text, including IEEE 754^[28] binary32, binary64 and binary128 formats, shall satisfy the following regular expression:^[21]

where the non-numeric IEEE 754 entities NaN (Not a Number), +∞ and –∞ are serialized as NaN, +Inf and -Inf, respectively.

Examples:

8.3.4 White Space

For textual serializations of all scalar types, leading and trailing white space (represented as the \s character class in regular expressions) is irrelevant, should not be generated by encoders, and must be ignored by decoders.

8.4.1 Property Identifier

A property identifier must be a sequence of one or more 8-bit ASCII characters^[20] satisfying the following regular expression:^[21]

Examples:

The colon separator (':', ASCII code point 58₁₀ = 3A₁₆) may be used to organize a set of properties into customary groups known as namespaces. Namespaces can be useful to improve structuration of properties by defining logical and semantic categories.

A property identifier must be unique for the object with which the property is associated. For example, all the properties of a given image must have unique identifiers, but two properties associated with different images may have the same identifier, or a property associated with the whole XISF unit may have the same identifier as another property associated with an image, etc.

There is no specific limit for the length of a property identifier.

8.4.2 Property Value

A property value is a data object associated with a property identifier. A property value has a predefined XISF property type, which determines its structure and behavior.

8.4.3 Property Format Specifier

A property format specifier may be associated with a property to control generation of readable plain text representations of the property value in a standardized way.

A property format specifier is a list of one or more format tokens separated by semicolon ASCII characters (';', ASCII code point 59₁₀ = 3B₁₆):

White space is irrelevant in a property format specifier and must be ignored. The following format tokens are supported by this specification:

width:count

count is a plain text representation of an unsigned integer. If the length n in characters of the represented value is less than the value of count, the represented value shall be padded with (n – count) padding characters—see the fill token below. The location of padding characters depends on the current alignment—see the align token below.

If no width token is specified, the value shall be represented using the minimum number of characters necessary, that is, no padding will be used by default.

fill:char

char is a single ASCII character that shall be used as a filling character for padded representations—see the width token above.

When no fill token is specified, the default padding character shall be the ASCII space character (ASCII code point 32₁₀ = 20₁₆).

align:mode

mode defines the alignment used for padded representations of all scalar types (see the width token above). mode must be one of:

left

Padding characters shall be appended at the end of the represented value.

right

Padding characters shall be prepended at the beginning of the represented value.

center

If the length n of the padding space is even, the same number n/2 of padding characters shall be prepended and appended at the beginning and the end of the represented value, respectively. If the padding length n is odd, n/2+1 padding characters shall be prepended at the beginning and n/2 padding characters shall be appended at the end of the represented value.

When not specified, the default alignment shall be right, as described above.

sign:mode

mode defines how a sign character is used for representations of numeric values. mode must be one of:

auto

Either a minus sign ASCII character ('-', ASCII code point 45₁₀ = 2D₁₆) or a Unicode minus sign character ('−', U+2212) shall be prepended to a representation of a scalar if the represented value is less than zero. If the represented value is zero or greater than zero, a sign character shall not be prepended.

force

Either a minus sign ASCII character ('-', ASCII code point 45₁₀ = 2D₁₆) or a Unicode minus sign character ('−', U+2212) shall be prepended to a representation of a scalar if the represented value is less than zero, and a plus sign ASCII character ('+', ASCII code point 43₁₀ = 2B₁₆) shall be prepended if the value is greater than zero.

In all cases, if the numeric value is being represented as zero (after a possible truncation or rounding operation), a sign character must not be prepended to the represented value.

When not specified, the default sign mode shall be auto, as described above.

A decoder must ignore the sign format token for representations of non-numeric values.

precision:count

count is a plain text representation of an unsigned integer, whose value is the precision of the representation of a floating point value. The precision shall be interpreted according to the current floating point mode (see the float token below):

• For a representation of a floating point scalar when the floating point mode is scientific or fixed, the precision is the minimum number of digits to appear after the decimal separator.
• For a representation of a floating point scalar when the floating point mode is auto, the precision is the maximum number of significant digits.

The represented floating point scalar shall be rounded to the nearest value with the required number of decimal digits.

If no precision token is specified, the default precision shall be 6.

A decoder must ignore the precision format token for representations of non-numeric or integer numeric values.

float:mode

mode defines the floating point mode used for representations of floating point numeric scalars. mode must be one of:

auto

The floating point value shall be represented using printf's 'g' mode.^[22] The floating-point value shall be represented in scientific or fixed floating point mode, depending on the value being converted and the current precision, to generate the shortest possible text representation.

scientific

The floating point value shall be represented in exponential notation. Ignoring possible padding characters, the representation shall satisfy the following regular expression:^[21]

[-+]?[0-9]+\.[0-9]+[eE][-+][0-9]+

fixed

The floating point value shall be represented in fixed-point decimal notation. Ignoring possible padding characters, the representation shall satisfy the following regular expression:

[-+]?[0-9]+(\.[0-9]+)?

When not specified, the default floating point mode shall be auto, as described above.

A decoder must ignore the float format token for representations of non-numeric or integer numeric values.

bool:mode

mode defines how Boolean values are represented. mode must be one of:

alpha

Boolean values shall be represented as the plain text words false and true.

numeric

The integers 0 and 1 shall be used to represent the Boolean values false and true, respectively.

When not specified, the default mode shall be alpha.

A decoder must ignore the bool format token for representations of non-Boolean values.

base:radix

radix defines the numeric base for the representation of an integer value. radix must be one of:

bin

The integer value shall be represented as a binary number using exclusively the digits '0' and '1'.

oct

The integer value shall be represented as an octal (base 8) number using the digits from '0' to '7'.

dec

The integer value shall be represented as a decimal number using the digits from '0' to '9'.

hex

The integer value shall be represented as an hexadecimal (base 16) number using the digits from '0' to '9' and from 'a' to 'f' to represent the numbers from 0 to 9 and from 10 to 15, respectively.

When not specified, the default value of radix shall be dec, that is, decimal representations shall be generated for integer numbers by default.

A decoder must ignore the base format token for representations of non-integer values.

unit:text

text is a Unicode text fragment that, if present, must represent the unit in which the property value is expressed. The multiplication, division and raise operators, '*', '/' and '^' respectively, can be used to represent units. For example:

"unit:m/s"
"unit:erg*s^−1*cm^2*Hz^−1"

In the second example the represented unit must be interpreted as .

A decoder shall follow these rules to apply a format specifier to structured numeric properties:

• A format specifier applied to a complex property shall apply to the individual complex and imaginary parts.
• A format specifier applied to a vector property shall apply to all vector components.
• A format specifier applied to a matrix property shall apply to all matrix elements.

For examples of property format specifiers, see the Property core element.

8.4.4 Property Types

XISF property types are organized into seven categories: scalar, complex, string, time point, vector, matrix and table.

8.5.1 Structure and Properties

In the context of this specification, an image is an object with the following structure and properties:

• An image is a set of scalars or complex numbers structured as a non-empty collection of -dimensional arrays.^[50]
• The dimensionality of the image is .
• Each -dimensional array is known as a channel or (hyper)plane of the image.
• All image channels have identical lengths in each one of their dimensions.
• Let be the number of channels in the image. Any channel must be addressable by its channel index , an integer such that .
• Let be the length of any channel in the -th dimension, .
• An image with any length for is an empty image. Empty images cannot be serialized in an XISF unit.
• A pixel coordinate is an integer array index such that .
• Any -tuple formed with the set of scalars or complex numbers at the same pixel coordinates is a pixel.
• The components of a pixel are pixel samples.
• Any pixel must be addressable by its -tuple of pixel coordinates.
• Any pixel sample must be addressable by the -tuple of channel index and pixel coordinates.
• The total number of pixels in an image is .
• The total number of pixel samples in an image is .
• For images with a visual representation role, pixel samples must be representable in a color model.^{[54] [43]}
• The color model where pixel samples are represented, if defined, should be augmented with a number of viewing conditions and colorimetric properties, which define the color space^[29] of the image.
• The first channels strictly required to define the color model (or color space) of an image, with indexes , are nominal channels.
• Excess channels beyond nominal channels, with indexes , are collectively known as alpha channels.
• The roles of alpha channels are implementation-defined; however, for images with a visual representation role the first alpha channel, at index , should define the transparency of the image for alpha-compositing operations.^[60]
• Every real or integer image defines a visually representable numerical range, which we formalize as a representable range property.

The mathematical symbols and terminology introduced in the above list will be used, unless otherwise noted, in the rest of this section.

Figure 1 — Structure of a two-dimensional image.

8.5.2 Geometrical Conventions

In a two-dimensional image we have and the lengths and are known as the width and height of the image, respectively. Conventionally, the dimensions and are known as the X-axis and Y-axis, respectively. It is customary to use the symbols and to represent coordinates in the first and second dimensions, respectively. We also say that is the horizontal axis and is the vertical axis. The point with pixel coordinates is said to be the top-left corner or the origin of the image. Note that all of these words don't necessarily imply any particular orientation of the represented image; they are just conventional designations.

In a three-dimensional image, and the dimensions , and are the width, height and depth of the image, respectively. The dimensions , and are known conventionally as the X-axis, Y-axis and Z-axis, respectively. It is customary to use the symbols , and to represent coordinates in the first, second and third dimensions, respectively. is the horizontal axis, is the vertical axis and is the depth axis. The point with pixel coordinates is said to be the origin of the image. Again, these designations are purely conventional and don't imply any particular representation of the image.

For one-dimensional images and images with dimensionalities higher than three, such as tesseracts and other hypercubes, there are no conventional names for axes and lengths. Normally these structures are manipulated as mathematical objects in purely abstract terms without a perceptual meaning or a visual role.

8.5.3 Pixel Storage Models

Two pixel storage models are formalized by this specification: planar and normal. The planar storage model is appropriate for applications that store and organize images by separate channels in memory. The normal storage model is best suited for applications that organize images by pixels, that is, applications that store the components of each pixel at consecutive memory locations.

Irrespective of the pixel storage model, the total space in bytes required to store an uncompressed image channel equals , where is the size in bytes of a pixel sample. Similarly, the total space in bytes required to store an uncompressed image is .

8.5.3.1 Planar Pixel Storage Model

In this model each channel is stored in a separate block:

• In the planar storage model, each channel of an image shall be stored as a contiguous sequence of pixel samples.
• For a given channel index , all pixel samples shall be stored in pixel coordinate order. The coordinates of the stored sequence of pixel samples can be represented as:
  
  
  [1]

Figure 2 — A two-dimensional image in the planar pixel storage model. Each square represents a pixel sample with its coordinates written vertically, where is a channel index and and are pixel coordinates. All pixel samples are stored as a single contiguous block from top to bottom and left to right (arrows indicate storage order).

8.5.3.2 Normal Pixel Storage Model

In this model all pixel samples are stored in a single block:

• In the normal storage model, all pixel samples of an image shall be stored as a contiguous sequence.
• All pixels shall be stored in pixel coordinate order. The coordinates of the stored sequence of pixel samples can be represented as:
  
  
  [2]

Figure 3 — A two-dimensional image in the normal pixel storage model. As in Figure [2], each square represents a pixel sample with its coordinates written vertically. Colors have been used to indicate image channels. As you can see by comparing both figures, in the normal model pixel samples are grouped by coordinates (by rows and columns in the case of a 2-D image) instead of by channels.

8.5.4 Color Spaces

The following color spaces are formally supported by this specification for storage of pixel data in XISF units: Grayscale (monochrome), RGB, and CIE L*a*b*.^[30]

An in-depth description of color spaces is beyond the scope of this specification. The reader should refer to the literature for further information on this subject; for example, see references ^[29], ^[54], ^[57] and ^[61].

To remove any possible ambiguity in the specification of CIE L*a*b*, we'll describe the necessary color space transformation algorithms in the next subsections.

8.5.4.1 RGB Working Space

All color space transformations shall be performed relative to a colorimetrically defined RGB working space (RGBWS) associated with the image. An RGB working space is a set , where:

• is a reference white. In this specification, all RGB working space parameters shall be relative to the standard D50 reference white.^[35]
• is an exponent for linearization of RGB components.
• and are the chromaticity coordinates of the RGB primaries.
• are the luminance coefficients of the RGB primaries.

All chromaticity coordinates and luminance coefficients shall be normalized to the [0,1] range.

For spaces not originally defined with respect to the D50 reference white, a chromatic adaptation algorithm must be applied to convert coordinates and coefficients to D50. The Bradford chromatic adaptation transform^[33] is recommended.

When no RGB working space is specified for a given image, the default RGBWS associated with the image shall be the sRGB space.^[31] The chromaticity coordinates and luminance coefficients of sRGB relative to D50 (after chromatic adaptation from the D65 reference white with the Bradford algorithm) are the following:

The sRGB space uses a special linearization function instead of a gamma exponent, as described below.

The RGBWS associated with a color image, either explicitly or by default, shall be used for all required color space transformations when the image is serialized encoded in a color space different from RGB. For example, if a color image is being stored encoded in the CIE L*a*b* space, an encoder must convert its pixel sample values from RGB to CIE L*a*b* using its associated RGBWS and the corresponding color space conversion algorithm, as described below. Conversely, if an image has been stored encoded in CIE L*a*b*, a decoder must use its associated RGBWS and the appropriate algorithm to convert pixel samples from CIE L*a*b* to RGB.

8.5.4.2 RGB to CIE XYZ Conversion

Let R, G, B be the nominal components of a pixel in the RGB color space. The nominal components R', G', B' in the linear RGB space are

[3]

If the RGB working space is the sRGB space,^[31] then a special function must be used instead of the equations above. Define the linearization function

[4]

Now we have, for the sRGB space:

[5]

The CIE XYZ components are given by

[6]

with the transformation matrix

[7]

8.5.4.3 CIE XYZ To RGB Conversion

Let X, Y, Z be the nominal components of a pixel in the CIE XYZ color space. The components R', G', B' in the linear RGB space can be found by multiplication with the inverse transformation matrix:

[8]

Then the RGB components are given by

[9]

If the RGB working space is the sRGB space,^[31] then a special function must be used instead of the equations above. Define the delinearization function

[10]

Now we have, for the sRGB space:

[11]

8.5.4.4 CIE XYZ to CIE L*a*b* Conversion

Define the function

[12]

with

[13]

Then the CIE L*a*b* components are:

[14]

8.5.4.5 CIE L*a*b* to CIE XYZ Conversion

Define the function

[15]

with and as defined in Equation [13]. Then the CIE XYZ components are:

[16]

where

[17]

8.5.5 Representable Range

The representable range is a property of every real or integer XISF image, that is, of any image whose pixel samples are floating point or integer scalars. It is the range of pixel sample values that can be represented on display devices, as we describe below. We say that and are the black point and white point of the image, respectively.

Consider an abstract device able to generate image representations for pixel sample values in the range. We call this range the device's input range, and we conventionally call and black and white, respectively, in the context of image representations generated by . Pixel samples outside the representable range will generate invalid, saturated representations: Any pixel sample value will be represented as black, while any pixel sample value will be represented as white. Any pixel sample will generate a valid representation as a gray level directly proportional to the input pixel sample value. Assuming a device so defined, the representable range of the image shall be applied for each pixel sample by means of the following algorithm:

[18]

This algorithm is a simple linear mapping of pixel sample values from the representable range of an image to a device's input range.

For example, for an image being represented on a typical 8-bit output device, such as a computer display or a printer, we would have and . Another example is an image processing application working internally with normalized floating point pixel data in the range, which would apply the above algorithm with and (note that in this case the algorithm can be trivially simplified).

There is no default representable range for real images whose pixel samples are encoded as floating point scalars, so in these cases the representable range must be declared explicitly; see the bounds attribute of the Image core element for implementation details.

For images whose pixel samples are encoded as unsigned integer scalars, the default representable range shall be , where is the number of bits per pixel sample.

For complex images, i.e. for images whose pixel samples are complex numbers, the representable range property is undefined. The reason for this limitation is that the role of a visually representable range, as we have described it above, is unclear for pixel data in the frequency domain and other applications of complex numerical data. The methods used for representation of complex-valued pixels are left as implementation-defined by this version of the XISF specification.

For color images encoded in color spaces different from RGB, the representable range shall apply to pixel sample values once converted to the RGB color space.

8.5.6 Display Function

A display function (DF) is a mathematical transformation applied to modify the visual representation of an XISF image. A display function has a set of function parameters such that

• is a vector of midtones balance parameters,
• is a vector of shadows clipping point parameters,
• is a vector of highlights clipping point parameters,
• is a vector of shadows dynamic range expansion parameters,
• is a vector of highlights dynamic range expansion parameters,

with the following constraints for :

For DF vector parameter components, the , and subindexes correspond to the red, green and blue nominal channels of RGB color images, respectively. For grayscale images, the subindex corresponds to the unique grayscale nominal channel, and the and vector components are not applicable. Finally, the subindex applies to visualizations of the CIE L* component (or lightness) of color images.

A decoder that claims support of display functions shall implement the following algorithm. For a pixel sample , define the midtones transfer function

[19]

This is a smooth, continuous function passing through the points , and , where is a midtones balance DF parameter. A midtones balance of 0.5 defines a linear function. A midtones balance value below 0.5 increases the midtones, while a value above 0.5 darkens the midtones of the image. The above equation can be derived from the Bulirsch-Stoer algorithm ^[55] for evaluation of the diagonal rational function, given the three fixed points of the midtones transfer function.

Define the clipping function

[20]

and the expansion function

[21]

Now for each pixel sample of a given image plane or component , we define the display function as

[22]

The identity display function is defined by the following parameters :

[23]

When no display function is specified for an image, the identity DF shall be assigned by default.

For normalization to the [0,1] range, as required by Equations [19], [20] and [21], Equation [18] shall be used with and if the original pixel data are encoded with a different representable range.

Display functions are mostly useful for visualization of linear images, such as CCD and digital camera raw frames. Figure [4] shows a typical example with a deep-sky astronomical image.

Figure 4 — Display function example.

(a) Linear image. Integration of 15 CCD raw images of the M81/M82 region.

(b) Linear image visualized with display function parameters , , and .

(c) Linear image visualized with display function parameters , , and .

In all cases dynamic range expansion parameters have the default values and . Display function parameters have been computed adaptively based on robust image statistics.

a

b

c

8.5.7 Adaptive Display Function Algorithm

In this subsection we describe an algorithm for the calculation of display functions based on robust image statistics. This algorithm, which has proven to yield excellent results for automatic visualization of most linear images, is recommended for all encoders claiming support for display functions.

For simplicity, let's consider a two-dimensional image; if necessary, the algorithm can be extended trivially to higher dimensions. Assume also, for the sake of simplicity, that the representable range of the image is . Consider an image channel with index , and recall that image dimensions are symbolized by and respectively for the X and Y axes. The normalized median absolute deviation of an image channel is given by

[24]

where is the sample median function,^[56] represents the pixel sample at coordinates , and is the median of all pixel samples in channel . The constant 1.4826 makes the median absolute deviation consistent with the standard deviation of a normal distribution.

Define the parameters:

Target mean background in the range. This parameter controls the global illumination of the displayed image. The recommended default value is .

Clipping point in units of , measured from the median . This parameter controls the overall contrast of the displayed image. The recommended default value is .

Note that these parameters are valid for all images and image channels. Set

[25]

Compute the clipping points

[26]

[27]

and the midtones balance

[28]

where is the midtones transfer function defined by Equation [19]. Setting and , now we have the whole set of parameters to apply an automatic display function to a channel of the image (see Equation [22]).

For RGB color images, a side effect of this algorithm is the relative alignment of the three histogram peaks, which tends to yield an effective white balance correction. The algorithm can be modified easily to apply a single set of DF parameters to all nominal channels, which preserves the existing color balance. In such case we can calculate, for example:

[29]

[30]

[31]

[32]

Figure 5 — Adaptive display function examples.

(a) Linear image. A single raw frame acquired with a DSLR camera.

(b) Linear image (a) visualized with separate adaptive display functions computed for each nominal channel. The original color balance of the linear data has been altered.

(c) Linear image (a) visualized with a single adaptive display function computed by Equations [29], [30], [31] and [32]. Note that the original color balance has been preserved.

(d) Linear RGB color image of M74. Composition of three integrated CCD images.

(e) Linear image (d) visualized with separate adaptive display functions computed for each nominal channel.

(f) Linear image (d) visualized with a single adaptive display function.

(g) Histogram of (d), magnified horizontally by a factor of 25.

In all cases adaptive DFs have been computed with default target background and clipping point parameters, as described in the text. Image of M74 courtesy of Calar Alto Observatory / Vicent Peris.

a

b

c

d

e

f

g

9.1.1 Monolithic XISF Unit

The contents of a monolithic XISF unit (Figure [6]) shall be stored in a single monolithic XISF file, which must include a unique XISF header and zero or more attached XISF data blocks.

Figure 6 — Structure of a monolithic XISF unit.

9.1.2 Distributed XISF Unit

The contents of a distributed XISF unit (Figure [7]) shall be stored in a unique XISF header file plus zero or more external XISF data blocks, available as local or remote resources. External XISF data blocks may be stored either in XISF data blocks files or in generic files.

Figure 7 — Structure of a distributed XISF unit.

10.5.1 Checksums of Compressed Blocks

When a checksum attribute is included in the XML element serializing a compressed data block, an encoder shall compute the corresponding cryptographic digest for the compressed data, and never from the original, uncompressed data. If a checksum verification fails for a compressed data block, a decoder must not attempt to decompress the altered data, as this might cause a vulnerability that could be exploited.

10.5.2 Byte Shuffling

For data blocks structured as contiguous sequences of 16-bit or larger integer or floating point numbers, a reversible byte shuffling routine can greatly improve compression ratios by increasing data locality, i.e. by redistributing the sequence such that similar byte values tend to be placed close together.

For compression of XISF data blocks, an optional byte shuffling algorithm can be applied before data compression. A reverse shuffling (or unshuffling) must then be applied after decompression to recover the original data.

This byte shuffling algorithm can be described as follows. Assume an input sequence of data items:

[33]

Let's assume also that each data item is composed of bytes. We can then rewrite the entire unshuffled sequence to show the individual bytes as follows:

[34]

The byte shuffling transform consists of rearranging all bytes such that the subsets of equally significant bytes are stored as compact subsequences in ascending order:

[35]

This notation gives a good implementation hint, and also shows that the algorithm is obviously a no-op for 8-bit data, that is when . The following code fragment provides a practical C++ implementation of the byte shuffling algorithm described above, with the corresponding reverse transform.

#include <cstdint>
#include <string.h>

/*!
 * Byte shuffling algorithm.
 *
 * output      The output array, where the shuffled array will be stored. This
 *             array must have capability for at least size bytes.
 *
 * input       The source unshuffled array.
 *
 * size        Length in bytes of the arrays.
 *
 * itemSize    Length of an array item.
 */
void Shuffle( uint8_t* output, const uint8_t* input, size_t size, size_t itemSize )
{
   if ( size > 0 )
      if ( itemSize > 0 )
         if ( input != nullptr )
            if ( output != nullptr )
            {
               size_t numberOfItems = size / itemSize;
               uint8_t* s = output;
               for ( size_t j = 0; j < itemSize; ++j )
               {
                  const uint8_t* u = input + j;
                  for ( size_t i = 0; i < numberOfItems; ++i, ++s, u += itemSize )
                     *s = *u;
               }
               ::memcpy( s, input + numberOfItems*itemSize, size % itemSize );
            }
}

/*!
 * Reverse byte shuffling algorithm.
 *
 * output      The output array, where the unshuffled array will be stored.
 *             This array must have capability for at least size bytes.
 *
 * input       The source shuffled array.
 *
 * size        Length in bytes of the arrays.
 *
 * itemSize    Length of an array item.
 */
void Unshuffle( uint8_t* output, const uint8_t* input, size_t size, size_t itemSize )
{
   if ( size > 0 )
      if ( itemSize > 0 )
         if ( input != nullptr )
            if ( output != nullptr )
            {
               size_t numberOfItems = size / itemSize;
               const uint8_t* s = input;
               for ( size_t j = 0; j < itemSize; ++j )
               {
                  uint8_t* u = output + j;
                  for ( size_t i = 0; i < numberOfItems; ++i, ++s, u += itemSize )
                     *u = *s;
               }
               ::memcpy( output + numberOfItems*itemSize, s, size % itemSize );
            }
}

10.5.3 Zlib Compression

The deflate compression algorithm^[2] and the standard zlib format^[1] are formally supported by this first XISF specification as one of the standard XISF compression codecs.

In particular, the implementation written by Jean-Loup Gailly and Mark Adler, the well-known zlib library,^[64] is recommended by this specification.

An XML element serializing the contents of an XISF data block compressed with the zlib codec must have a compression attribute with the following syntax:

compression="zlib:uncompressed-size"

where uncompressed-size is a plain text representation of an unsigned integer whose value is the size in bytes of the original uncompressed data.

Example:

<Image geometry="6:6:3" sampleFormat="UInt8" colorSpace="RGB" location="embedded">
   <Data compression="zlib:108" encoding="base64">
      eJxjYGBg+A+GEPCfAYkJFQZSUPZ/KBtTBFMXOuc/AwCjKyPd
   </Data>
</Image>

This example serializes a tiny RGB color image of 6x6 pixels, compressed and embedded within an Image element. The following example:

<Property id="Test" type="ByteArray" length="34" compression="zlib:34" location="inline:base64">
   eNoLycgsVgCiRIWS1OISBV2FENfgECBlaGRsYmpmbmFpAACzWQkd
</Property>

shows a Property element serializing a ByteArray XISF property with zlib compression as an inline data block.

This example shows a zlib-compressed image with a SHA-1 checksum:

<Image geometry="960:540:3" sampleFormat="Float32" bounds="0:1"
       colorSpace="RGB" compression="zlib:6220800" location="attachment:4570:1428362"
       checksum="sha1:1ad9a10249b7574f97c7b4771f13924603b9852d" />

10.5.4 Zlib Compression with Byte Shuffling

This compression codec is identical to zlib compression, except that the byte shuffling transform must be applied to the data block before compressing it. The reverse byte shuffling transform shall be applied after decompression to recover the original order of bytes in the uncompressed data.

An XML element serializing the contents of an XISF data block compressed with the zlib with byte shuffling codec must have a compression attribute with the following syntax:

compression="zlib+sh:uncompressed-size:item-size"

where uncompressed-size and item-size are plain text representations of unsigned integers whose values are, respectively, the size in bytes of the original uncompressed data and the length in bytes of a data item, required for the byte shuffling algorithm.

10.5.5 LZ4 Compression

the LZ4 compression algorithm,^[65] created by Yann Collet, is formally supported by this first XISF specification as one of the standard XISF compression codecs.

LZ4 is a lossless data compression algorithm focused on compression and decompression speed, featuring an extremely fast decoder suitable for real-time operation on modern hardware. The reference implementation in C by the author ^[66] is recommended by this specification.

An XML element serializing the contents of an XISF data block compressed with the LZ4 codec must have a compression attribute with the following syntax:

compression="lz4:uncompressed-size"

where uncompressed-size is a plain text representation of an unsigned integer whose value is the size in bytes of the original uncompressed data.

10.5.6 LZ4 Compression with Byte Shuffling

This compression codec is identical to LZ4 compression, except that the byte shuffling transform must be applied to the data block before compressing it. The reverse byte shuffling transform shall be applied after decompression to recover the original order of bytes in the uncompressed data.

An XML element serializing the contents of an XISF data block compressed with the LZ4 with byte shuffling codec must have a compression attribute with the following syntax:

compression="lz4+sh:uncompressed-size:item-size"

where uncompressed-size and item-size are plain text representations of unsigned integers whose values are, respectively, the size in bytes of the original uncompressed data and the length in bytes of a data item, required for the byte shuffling algorithm.

10.5.7 LZ4_HC Compression

the LZ4_HC variant of the LZ4 compression algorithm ^[65] by Yann Collet is formally supported by this first XISF specification as one of the standard XISF compression codecs.

LZ4_HC is as fast as LZ4 for decompression, but achieves much higher compression ratios at the cost of a slower compression. The reference implementation in C by the author ^[66] is recommended by this specification.

An XML element serializing the contents of an XISF data block compressed with the LZ4_HC codec must have a compression attribute with the following syntax:

compression="lz4hc:uncompressed-size"

where uncompressed-size is a plain text representation of an unsigned integer whose value is the size in bytes of the original uncompressed data.

10.5.8 LZ4_HC Compression with Byte Shuffling

This compression codec is identical to LZ4_HC compression, except that the byte shuffling transform must be applied to the data block before compressing it. The reverse byte shuffling transform shall be applied after decompression to recover the original order of bytes in the uncompressed data.

An XML element serializing the contents of an XISF data block compressed with the LZ4_HC with byte shuffling codec must have a compression attribute with the following syntax:

compression="lz4hc+sh:uncompressed-size:item-size"

where uncompressed-size and item-size are plain text representations of unsigned integers whose values are, respectively, the size in bytes of the original uncompressed data and the length in bytes of a data item, required for the byte shuffling algorithm.

11.1.1 Mandatory Property Attributes

A Property element shall have the following attributes:

id="property-id"

where property-id is a valid XISF property identifier, which shall be the identifier of the XISF property being serialized.

type="property-type"

where property-type is the name of an XISF property type, which shall be the data type of the XISF property being serialized.

11.1.2 Optional Property Attributes

A Property element may have the following optional attributes:

format="property-format-spec"

where property-format-spec is a valid XISF property format specifier for the XISF property being serialized.

XISF decoders claiming support for property format specifiers should apply them, as appropriate, to generate plain text representations of scalar values. This includes all scalar property types, the components of complex properties, string properties (where only width and align format tokens should be taken into account), the components of vector properties, and the elements of matrix properties.

comment="property-comment"

where property-comment is a String property value. This attribute is intended to provide a descriptive comment about the property being serialized.

The use of property comments is discouraged in general. Always try to assign descriptive, self-documenting names to properties, including namespaces when appropriate. This makes it seldom necessary to write property comments.

Examples:

<Property id="FocalDistance" type="UInt32" value="2540" format="width:8;align:center" />
<Property id="Magnitude" type="Float32" value="1.25"
                                 format="width:6;precision:2;float:fixed;sign:force" />
<Property id="Flags" type="UInt16" value="0xff39" format="width:8;base:hex;fill:." />
<Property id="Coefficients" type="Vector64" length="1234"
                                 location="attachment:4096:9872" format="width:10;precision:3" />

These examples would generate the following plain text representations:

"  2540  "
" +1.25"
"....ff39"
"      32.1, -1.24e-08"

In the last example, note that the float:auto format token is implicitly being used by default. Only the first two vector components are shown, and in this example we assume that the decoder application is representing vectors as comma-separated lists of components, which is not part of this specification and hence is not mandatory.

11.1.4 Serialization of Scalar Properties

A Property element serializing a scalar XISF property shall have a value attribute, whose value shall be a valid plain text serialization of the property value. Typically, in these cases the Property element is an empty XML element.

Examples:

<Property id="HasData" type="Boolean" value="1" />
<Property id="Flags" type="UInt32" value="0x8000FFA0" />
<Property id="Volume" type="Float64" value="1.1234e+04" />

11.1.5 Serialization of Complex Properties

A Property element serializing a Complex32, Complex64 or Complex128 property shall have a value attribute, whose value shall serialize the value of the XISF property as follows:

value="(real,imag)"

where real and imag are, respectively, plain text representations of the floating point real and imaginary parts of the complex number. Typically, in these cases the Property element is an empty XML element.

Example:

<Property id="PeakElement" type="Complex32" value="(0.123,-0.735e-02)" />

11.1.6 Serialization of String Properties

A Property element serializing a String property shall not have a value attribute, and must serialize the property value either directly in its character data contents, or as an XISF data block.

Examples:

<Property id="XISF:BriefDescription" type="String">Definitely one of my very best images.</Property>
<Property id="ALongString" type="String" location="attached:17600:8192" />
<Property id="AnEncodedString" type="String"
                  location="inline:base64">VGhlIHF1aWNrIGJyb3duIGZveA==</Property>
<Property id="AnExternalDocument" type="String"
                  location="url(http://mysite.example.com/MyTextDocument.txt)" />

When a string is serialized unencoded directly in the character contents of a Property element, keep in mind that all of the white space between the starting and ending tags is significant and a compliant decoder must preserve it. To prevent unwanted leading and trailing spaces, the Property element should be generated as a single text line in these cases.

11.1.7 Serialization of TimePoint Properties

A Property element serializing a TimePoint property shall have a value attribute, whose value shall be the plain text representation of the TimePoint value. Typically, in these cases the Property element is an empty XML element.

Examples:

<Property id="CreationTime" type="TimePoint" value="2014-12-01T18:07:54Z" />
<Property id="Observation:StartTime" type="TimePoint" value="2015-01-23T19:52:31.46Z" />

White space is irrelevant in a TimePoint serialization, so it should not be generated by encoders and must be ignored by decoders.

11.1.8 Serialization of Vector Properties

A Property element serializing a vector property:

• Shall not have a value attribute.
• Shall have a length attribute. The value of the length attribute must be a plain text representation of an unsigned integer, whose value must be the vector length, that is, the number of components in the vector.
• Shall serialize the value of the XISF property as an XISF data block.

Example:

<Property id="TestProperty" type="ByteArray" length="34" location="inline:base64">
   VGhpcyBpcyBhIHRlc3QgLSBURVNUIC0gMTIzNDU2Nzg5MA==
</Property>

11.1.9 Serialization of Matrix Properties

A Property element serializing a matrix property:

• Shall not have a value attribute.
• Shall have a rows attribute. The value of the rows attribute must be a plain text representation of an unsigned integer, whose value must be the number of rows in the matrix.
• Shall have a columns attribute. The value of the columns attribute must be a plain text representation of an unsigned integer, whose value must be the number of columns in the matrix.
• Shall serialize the value of the XISF property as an XISF data block.

Example:

<Property id="AstrometricSolution" type="F64Matrix" rows="428" columns="16"
                           location="path(@header_dir/astrometry/solution.dat)" />

11.2.1 Field Element

A Structure element shall have at least one child Field element. Each Field element shall define a table field in the table structure being defined by its parent Structure element. Each Field element must have the following mandatory attributes:

id="field-id"

where field-id is a valid XISF property identifier, which shall be the identifier of the table field being defined.

type="field-type"

where field-type is the name of an XISF property type, which shall be the type of the table field being defined.

A Field element may have the following optional attributes:

format="field-format-spec"

where field-format-spec is a valid XISF property format specifier, which shall be the format specifier of the table field being defined.

Decoders claiming support for property format specifiers should apply table field formats, when available, to generate plain text representations of table cell values, as appropriate. See the Property core element for more information and examples.

header="field-header"

where field-header is a String property value, which shall be the header or title of the table field being defined.

XISF decoders should use field headers, when available, as column headers or titles in text-based representations of table properties in tabular form.

In the following example a Structure element defines the structure of a table to store a list of Messier objects:

<Structure uid="MessierCatalogStructure">
   <Field id="number" type="UInt8" header="Messier Number" />
   <Field id="ngc_ic" type="String" header="NGC/IC" />
   <Field id="commonName" type="String" header="Common Name" />
   <Field id="objectType" type="String" header="Object Type" />
   <Field id="distance" type="Float32" header="Distance" format="float:fixed;precision:2;unit:kly" />
   <Field id="constellation" type="String" header="Constellation" />
   <Field id="magnitude" type="Float32" header="Apparent Magnitude" format="float:fixed;precision:1" />
</Structure>

11.3.1 Mandatory Table Attributes

Every Table element shall have the following attribute:

id="property-id"

where property-id is a valid XISF property identifier, which shall be the identifier of the XISF property being serialized.

11.3.2 Optional Table Attributes

A Table element may have the following optional attributes:

caption="table-caption"

where table-caption is a String property value. Table captions should be used, when available, as titles for tabular representations of table properties.

rows="row-count"

where row-count is a plain text serialization of the number of rows in the table. When present, this attribute must correspond to the actual number of rows defined in the table being serialized.

columns="columns-count"

where columns-count is a plain text serialization of the number of columns in the table. When present, this attribute must correspond to the actual number of columns defined in the table being serialized.

comment="property-comment"

where property-comment is a String property value. This attribute is intended to provide a descriptive comment about the table property being serialized.

As happens with the rest of property types, the use of table comments is discouraged. Always try to assign descriptive, self-documenting names to properties, including namespaces when appropriate. This makes it seldom necessary to write property comments.

11.3.3 Row and Cell Elements

A Table element may have zero or more child Row elements. Each Row element serializes the sequence of cells in a table row.

Each Row element shall have one or more child Cell elements, each of them serializing a table cell value. The number and order of child Cell elements in each Row element shall be the number and order of table fields defined in the structure of the table being serialized. In addition, the objects serialized by Cell elements must be valid XISF property values for their corresponding table field types. In other words, there must be a one-to-one correspondence between cell elements and table fields.

A child Row element of a Table element shall have child Cell elements exclusively; no other contents are allowed, including character data contents.

A child Cell element of a child Row element of a Table element shall serialize its corresponding table cell value exactly as a Property element serializing an XISF property of the corresponding field type, except that the id, type and format attributes must not be used for Cell elements. For example, a Cell element serializing a scalar property must have a value attribute where the scalar value will be represented as plain text. A Cell element for a string table field can have a location attribute if the string value is being serialized as an attachment, or serialize the string directly in its character contents.

The next example shows a Table element serializing a table of Messier objects (some parts of the code replaced with ... to shorten the example). In this case a child Reference element is being used to access the Structure element defined in the example of the previous section.

<Table id="MessierCatalog" caption="The Messier Catalog" rows="110" columns="7">
   <Reference ref="MessierCatalogStructure" />
   <Row>
      <Cell value="1" />
      <Cell value="NGC 1952" />
      <Cell value="Crab Nebula" />
      <Cell value="Supernova remnant" />
      <Cell value="6.5" />
      <Cell value="Taurus" />
      <Cell value="8.4" />
   </Row>
   <Row>
      <Cell value="2" />
      <Cell value="NGC 7089" />
      <Cell value="" />
      <Cell value="Globular cluster" />
      <Cell value="33" />
      <Cell value="Aquarius" />
      <Cell value="6.3" />
   </Row>
   <Row>
      <Cell value="3" />
      <Cell value="NGC 5272" />
      <Cell value="" />
      <Cell value="Globular cluster" />
      <Cell value="33.9" />
      <Cell value="Canes Venatici" />
      <Cell value="6.2" />
   </Row>
   ...
   <Row>
      <Cell value="31" />
      <Cell value="NGC 224" />
      <Cell value="Andromeda Galaxy" />
      <Cell value="Spiral galaxy" />
      <Cell value="2540" />
      <Cell value="Andromeda" />
      <Cell value="3.4" />
   </Row>
   ...
</Table>

The following example shows a Table element serializing a set of variable star observations. The table includes fields to serialize the star designation and the total number of observations available, as well as a ByteArray field to store the observational data. The observations have been serialized as attached data blocks with LZ4_HC compression and SHA-1 block checksums.

<Table id="obsvar_2016" caption="Observations of Selected Variable Stars in 2016">
   <Structure>
      <Field id="starName" type="String" header="Star" />
      <Field id="numObs" type="UInt32" header="Number of Observations" />
      <Field id="data" type="ByteArray" />
   </Structure>
   <Row>
      <Cell value="SS Cyg" />
      <Cell value="132729" />
      <Cell length="537068" compression="lz4hc:537068"
         location="attachment:4096:228002"
         checksum="sha1:1fe534b0f97d67b75800e7a3077ab26586b35959" />
   </Row>
   <Row>
      <Cell value="R CrB" />
      <Cell value="58135" />
      <Cell length="210580" compression="lz4hc:210580"
         location="attachment:623016:121555"
         checksum="sha1:f90215ad052df0d557b0a8089305247904e36174" />
   </Row>
   <Row>
      <Cell value="TT Ari" />
      <Cell value="99702" />
      <Cell length="429993" compression="lz4hc:429993"
         location="attachment:1327024:260077"
         checksum="sha1:dea20adf1d1397a136da45309c6d1af29e215f34" />
   </Row>
</Table>

11.4.1 Mandatory Metadata Properties

The Metadata element must contain child Property elements serializing the following XISF properties:

XISF:CreationTime

A TimePoint property. The value of this property shall represent the date and time the XISF header has been created.

Example:

<Property id="XISF:CreationTime" type="TimePoint" value="2014-12-09T12:38:15Z" />

XISF:CreatorApplication

A String property, whose value must be a plain text readable identification of the software application that has created the XISF header. The value of this property must contain the name and version of the application in human-readable form.

Example:

<Property id="XISF:CreatorApplication" type="String">PixInsight 01.08.03.1123</Property>

11.4.2 Optional Metadata Properties

In addition, the following properties are optional for the Metadata element, but should be serialized as child Property elements when appropriate:

XISF:CreatorModule

A String property. If the software that has created the XISF header (XISF:CreatorApplication) is a modular system where the XISF format has been implemented by a versioned subsystem or module, this property should be defined to provide a plain text readable identification of the subsystem or module that has created the XISF header. If defined, the value of this property must contain the name and version of the subsystem or module in human-readable form.

Example:

<Property id="XISF:CreatorModule" type="String">XISF module version 01.00.00.0024</Property>

XISF:CreatorOS

A String property. This property should be defined to provide a plain text readable identification of the operating system where the XISF header has been created. The following values must be used to identify several common operating systems:

Table 10
CreatorOS Property Values

Operating system	CreatorOS property value	Alternate property value
FreeBSD	FreeBSD
Linux	Linux
Apple macOS (formerly OS X)	macOS	OSX
Microsoft Windows	Windows

Example:

<Property id="XISF:CreatorOS" type="String">Linux</Property>

XISF:CompressionMethod

A String property. If the XISF unit contains compressed data blocks, this property should be defined to enumerate the applied compression codec(s) used. If more than one codec has been used, they should be specified as a comma-separated list.

Examples:

<Property id="XISF:CompressionMethod" type="String">zlib</Property>

<Property id="XISF:CompressionMethod" type="String">zlib+sh,lz4hc</Property>

XISF:CompressionLevel

An Int32 property. If the XISF unit contains compressed data blocks, this property should be defined to inform on the compression level used in the range from 1 to 100, where 1 means minimum compression and 100 corresponds to maximum compression.

Note that this is an abstract, codec-independent compression level. For example, the standard zlib^[1] codec defines an integer compression level in the range from 0 to 9 that controls the speed/compression balance. In the zlib case, its range [0,9] should be mapped to the codec-independent range [1,100].

In complex cases where multiple data blocks have been compressed with different codecs and/or varying parameters, this property should not be defined.

Example:

<Property id="XISF:CompressionLevel" type="Int" value="90" />

XISF:Author

An optional String property. The name(s) of the person(s) who have created the XISF unit.

Example:

<Property id="XISF:Author" type="String">James T. Kirk</Property>

XISF:Copyright

An optional String property. Copyright information applicable to the materials included in the XISF unit.

Example:

<Property id="XISF:Copyright" type="String">Copyright (c) 2014 Extragalactic Imaging
Corporation. All Rights Reserved.</Property>

XISF:BriefDescription

An optional String property. A brief description or caption for the materials included in the XISF unit. If this metadata property is specified, it should be a brief text not longer than 256 characters.

Example:

<Property id="XISF:BriefDescription" type="String">Messier 45, The Pleiades Cluster</Property>

XISF:Description

An optional String property. A description of the materials included in the XISF unit.

Example:

<Property id="XISF:Description" type="String" location="attached:2048:8325" />

XISF:Keywords

An optional String property. A comma-separated list of keywords or search index terms applicable to the materials included in the XISF unit, specified in decreasing order of relevance.

Example:

<Property id="XISF:Keywords" type="String">IC 342, spiral galaxy, deep-sky object</Property>

11.5.1 Mandatory Image Attributes

The following attributes of the Image element are either mandatory or required under the described conditions.

geometry="dim₁:...:dim_N:channel-count"

This attribute shall be specified for all Image elements.

Defines the geometry of an N-dimensional image. The number N ≥ 1 of dim items is the dimensionality of the image: N=1 for a one-dimensional image, N=2 for a two-dimensional image, etc. Each dim_i item is a plain text representation of an unsigned integer whose value, which must be greater than zero, is the corresponding length of the image on its i-th axis in pixel units. The last channel-count item is a plain text representation of an unsigned integer whose value, which must be greater than zero, is the number of existing image channels or planes.

For a two-dimensional or three-dimensional image, the first dimension corresponds to the X-axis of the image and the second dimension corresponds to its Y-axis. For a three-dimensional image, the third dimension corresponds to the Z-axis.

Example:

<Image geometry="960:540:3" sampleFormat="Float32" bounds="0:1"
       colorSpace="RGB" compression="zlib:6220800" location="attachment:4570:1428362" />

This example defines a two-dimensional image with three channels. Its width is 960 pixels and its height is 540 pixels.

sampleFormat="sample-format"

This attribute shall be specified for all Image elements.

Defines the data type used to represent the pixel samples of the image, also known as the sample format of the image. sample-format must be one of the following literals:

Table 11
sampleFormat Attribute Values

Sample data type	sampleFormat attribute value
Unsigned 8-bit integer	UInt8
Unsigned 16-bit integer	UInt16
Unsigned 32-bit integer	UInt32
Unsigned 64-bit integer	UInt64
Real IEEE 754[28] binary32 floating point	Float32
Real IEEE 754 binary64 floating point	Float64
Complex IEEE 754 binary32 floating point	Complex32
Complex IEEE 754 binary64 floating point	Complex64

bounds="lower:upper"

This attribute shall be specified for all Image elements serializing floating point real pixel data. It is optional for Image elements serializing integer and complex pixel data.

The bounds attribute defines the representable range of a real or integer image in the grayscale or RGB color spaces. lower is a plain text representation of a floating point number, whose value is the lower bound of the representable range, or the black point of the image. upper is a plain text representation of a floating point number, whose value is the upper bound of the representable range, or the white point of the image.

The bounds attribute is required for floating point real images, that is, it shall be defined for images where the value of the sampleFormat attribute is either Float32 or Float64.

For integer images, where the value of the sampleFormat attribute is UInt8, UInt16, UInt32 or UInt64, the bounds attribute is optional. If the bounds attribute is not specified for an integer image, then its representable range shall be [0,2ⁿ–1], where n is the number of bits per pixel sample. For integer n-bit images using representable ranges equal to their default [0,2ⁿ–1] range, the bounds attribute should not be specified.

For complex images, where the value of the sampleFormat attribute is Complex32 or Complex64, the bounds attribute is optional because the representable range is formally undefined for these images. Visual representation of complex-valued pixel data is left as implementation-defined by this version of the XISF specification.

For color images encoded in color spaces different from RGB, the representable range defined by the lower and upper bounds shall apply to pixel sample values once converted to the RGB color space.

imageType="type-spec"

This attribute must be generated by encoders—typically, by image acquisition applications—producing raw frames of the bias, dark, flat field and science/light types (see the table below). For the rest of image types this property is optional, but generating it is strongly recommended when appropriate.

type-spec shall be one of the following literals:

Table 12
imageType Attribute Values

Image type	imageType attribute value
Bias frame	Bias
Dark frame	Dark
Flat field	Flat
Light or science frame	Light
Integrated bias frame	MasterBias
Integrated dark frame	MasterDark
Integrated flat field	MasterFlat
Integrated light or science image	MasterLight
Defect map	DefectMap
Pixel rejection map, high values	RejectionMapHigh
Pixel rejection map, low values	RejectionMapLow
Slope map	SlopeMap

A master frame is the result of the integration of two or more individual frames or images of the same type.

A defect map is an integer or floating point real image where nonzero pixel sample values represent invalid or defective pixels. Defective pixels are typically ignored or replaced with plausible statistical estimates, such as robust averages of neighbor pixels.

Rejection maps are integer or floating point real images where each pixel sample value is proportional to the number of rejected pixels in an integration process at the corresponding pixel coordinates. Low and high rejection maps correspond, respectively, to rejected pixels below and above a central reference value (typically a robust location estimate such as the median of a set of integrated pixels). A rejection map sample value equal to the lower bound of the representable range corresponds to zero rejected pixels, while the upper bound indicates that all integrated pixels have been rejected.

Slope maps are integer or floating point real images where each pixel sample value is proportional to the slope of a straight line fitted to a set of integrated pixels at the corresponding pixel coordinates. A slope map value equal to the lower bound of the representable range corresponds to a horizontal line (or a slope of zero degrees), while the upper bound represents a vertical line (infinite slope).

11.5.2 Optional Image Attributes

pixelStorage="pixel-storage"

This attribute is optional for all Image elements.

Defines the pixel storage model used to organize the stored pixel data of the image. pixel-storage must be one of the following literals:

Table 13
pixelStorage Attribute Values

Pixel storage model	pixelStorage attribute value
Planar pixel storage model	Planar
Normal pixel storage model	Normal

For Image elements without a pixelStorage attribute, the default planar pixel storage model shall be assumed.

colorSpace="color-space"

This attribute is optional for all Image elements.

Defines the color model or color space where pixel sample values are represented for the serialized image. color-space must be one of the following literals:

Table 14
colorSpace Attribute Values

Color space	colorSpace attribute value
Grayscale (monochrome)	Gray
RGB	RGB
CIE L*a*b*	CIELab

For descriptions of these color spaces and the corresponding transformation algorithms, see the XISF Image section.

For Image elements without a colorSpace attribute, the default grayscale color space shall be assumed.

offset="sample-value"

This attribute is optional for all Image elements.

Defines a positive pixel sample value that has been added to every pixel sample in the image. An offset value (also known as pedestal) is necessary sometimes to ensure positivity of pixel data, mainly because of noise variations.

sample-value must be a plain text representation of a floating point scalar. Its value must be greater than or equal to zero, and can be subtracted from each pixel sample in the image to obtain zero-based pixel sample values. This operation is critical for image calibration and integration processes.

An offset should not be applied, and consequently this attribute should not be used, unless adding a positive pedestal is strictly necessary for the image being serialized, for the technical reasons described above. In other words, these offsets must not be used systematically or as a means to represent arbitrary operations.

For Image elements without an offset attribute, the default offset value shall be zero.

orientation="rotation"

This attribute is optional for all Image elements.

rotation defines geometric operations that can be applied to change the default orientation of the image. rotation must be one of:

0

The default image orientation should be preserved, so do nothing.

flip

Flip (reflect) the image horizontally.

90

Rotate the image by 90 degrees, counter-clockwise direction.

90;flip

Rotate the image by 90 degrees in the counter-clockwise direction, then flip it horizontally.

-90

Rotate the image by 90 degrees, clockwise direction.

-90;flip

Rotate the image by 90 degrees in the clockwise direction, then flip it horizontally.

180

Rotate the image by 180 degrees.

180;flip

Rotate the image by 180 degrees, then flip it horizontally (equivalent to a vertical reflection).

If the orientation attribute is present for an Image element, a decoder claiming support for image orientation should apply the appropriate rotation and/or reflection upon loading an image to be represented visually.

However, a decoder must not apply orientation transformations to images loaded for image processing tasks that depend on the physical disposition of pixel data. For example, an image calibration process should not reorient image data, since this might invalidate the application of master calibration frames.

id="image-id"

This attribute is optional for all Image elements. image-id shall be a sequence of ASCII characters satisfying the following regular expression:^[21]

[_a-zA-Z][_a-zA-Z0-9]*

This attribute may be used by a decoder to identify images in a software application. image-id must be considered as case-sensitive.

uuid="uuid"

This attribute is optional for all Image elements. It may be generated to uniquely identify (with overwhelming probability) an XISF image object.

uuid must be a plain text representation of a Universally Unique Identifier (UUID)^[7] in canonical form. Version 4 UUIDs must be used with a pseudo-random number generator of cryptographic quality. The XorShift1024* algorithm^{[58] [59] [62]} is recommended by this specification.

Example:

<Image uuid="c5c93b6d-9072-4e85-9548-1a5391377683"
       geometry="960:540:3" sampleFormat="Float32" bounds="0:1"
       colorSpace="RGB" compression="zlib:6220800" location="attachment:4570:1428362" />

11.5.3 Astronomical Image Properties

In this subsection we formalize a reduced set of Property core elements designed specifically to support astronomical image data. The Property elements described here may be generated by encoders as child elements of Image core elements. They may also be associated with images by means of uid attributes and child Reference elements.

The identifiers of these properties use namespaces to organize them into several fundamental categories: Observer, Organization, Observation, Instrument, and Processing. These properties have reserved identifiers that must not be used for purposes different from the ones described herein.

All of these properties are optional. However, all encoders—especially image acquisition and processing applications—should implement them as necessary and appropriate, following the norms and recommendations given in the list below.

11.6.1 Mandatory FITSKeyword Attributes

A FITSKeyword element shall define the following attributes:

name="keyword-name"

where keyword-name is the name of a FITS header keyword. Quoted from the FITS standard:^[49]

The keyword name shall be a left justified, 8-character, space-filled, ASCII string with no embedded spaces. All digits 0 through 9 (decimal ASCII codes 48 to 57, or hexadecimal 30 to 39) and upper case Latin alphabetic characters ‘A’ through ‘Z’ (decimal 65 to 90 or hexadecimal 41 to 5A) are permitted; lower case characters shall not be used. The underscore ( ‘_’, decimal 95 or hexadecimal 5F) and hyphen (‘-’, decimal 45 or hexadecimal 2D) are also permitted. No other characters are permitted.

value="keyword-value"

keyword-value is the value of a FITS header keyword.^[48] The HISTORY and COMMENT keywords don't have a value, so this attribute must be an empty string for these keywords.

comment="keyword-comment"

keyword-comment is the comment of a FITS header keyword.^[48]

Examples (some parts of the code replaced with ... to shorten the examples):

<Image geometry="2048:2048:1" sampleFormat="Float32" bounds="0:1"
                                 colorSpace="Gray" location="attachment:12288:16777216">
...
   <FITSKeyword name="DATE-OBS" value="'2012-03-15T02:55:15'" comment="Observation start time, UT"/>
   <FITSKeyword name="EXPTIME" value="300" comment="Exposure time in seconds"/>
   <FITSKeyword name="XBINNING" value="1" comment="Binning factor, X-axis"/>
   <FITSKeyword name="YBINNING" value="1" comment="Binning factor, Y-axis"/>
   <FITSKeyword name="HISTORY" value="" comment="Processed with magic techniques"/>
...
</Image>

In the next example, a FITSKeyword element has been defined somewhere in the XISF header with uid="KWD001", and has been associated with an image through a Reference element:

<Image ... >
...
   <Reference ref="KWD001" />
...
</Image>
...
<FITSKeyword ... uid="KWD001" ... />

Examples (some parts of the code replaced with ... to shorten the examples):

<Image geometry="4657:3452:4" sampleFormat="UInt8" colorSpace="RGB"
                                    location="attachment:4096:48227892">
...
   <ICCProfile location="attachment:48234496:28456"/>
...
</Image>

In the above example, the ICC color profile has been stored as an attached data block. The following example:

<Image ... >
...
   <ICCProfile compression="zlib:3024" location="inline:base64">
      eNq1lmdYE1kXx+9MeqMkAemEXoN0Aoj0LtKrjZAECCVASMCCDREVWFFEpCmCLAq44OpSZC2IBQ
      uLgBQVdYMsAsrr4io2VN5B9n10P74f9jzPnfnf35wz994zH+YPAKlPkCLgwQCAZIFIGOTpwoiI
      jGLgBgEOyAEaIAENNic9FXkMIGR4u7sy0pGkv6d/x9vhpdk9plcAgwH+v5Dh8tI5yOvcEC2KQR
      ...
      CFh98YEgFLtyW/BsA/feU/Av5Wh5JHhgWCar+xlBoAWHMIP5DOj/vKXINCGN/1gRnEi+UJeQLk
      qGF8XiZfEIecX8Dli/gpAgZfwPhHm/49v/bNK4t4G0Vf95mSuknIj4sXMbx4mUk8kYgRwOYkso
      VcY4a5qaklSI+1MF/qDBnxyJjfFxZe6wKAKwbgc+HCwnz1wsJn5OyoUQA6xf8FPPPKDg==
   </ICCProfile>
...
</Image>

shows a zlib-compressed, Base64-encoded ICC color profile serialized as an inline data block.

In the next example, an ICCProfile element has been defined somewhere in the XISF header with uid="TheProfile", and has been associated with an image through a Reference element:

<Image ... >
...
   <Reference ref="TheProfile" />
...
</Image>
...
<ICCProfile ... uid="TheProfile" ... />

11.8.1 Mandatory RGBWorkingSpace Attributes

These parameters shall be serialized by an RGBWorkingSpace element with the following required XML attributes:

gamma="gamma-spec"

gamma-spec can be one of:

• A plain text representation of a floating point number, whose value > 0 is the exponent of the RGBWS.
• The word sRGB (case-insensitive)—in this case the RGBWS shall use an sRGB^[31] gamma function instead of a fixed exponent.

x="x_R:x_G:x_B"

x_R, x_G and x_B are plain text representations of floating point numbers. The values of these attributes are, respectively, the chromaticity coordinates of the red, green and blue primary colors of the RGBWS.

y="y_R:y_G:y_B"

y_R, y_G and y_B are plain text representations of floating point numbers. The values of these attributes are, respectively, the chromaticity coordinates of the red, green and blue primary colors of the RGBWS.

Y="Y_R:Y_G:Y_B"

Y_R, Y_G and Y_B are plain text representations of floating point numbers. The values of these attributes are, respectively, the luminance coefficients of the red, green and blue primary colors of the RGBWS.

11.8.2 Optional RGBWorkingSpace Attributes

The following attribute is optional for any RGBWorkingSpace element:

name="rgbws-name"

where rgbws-name is an arbitrary sequence of Unicode characters that will be assigned as the name of the RGBWS for identification purposes.

Examples (some parts of the code replaced with ... to shorten the examples):

<Image ... >
...
   <RGBWorkingSpace x="0.648431:0.230154:0.155886"
          y="0.330856:0.701572:0.066044"
          Y="0.311114:0.625662:0.063224" gamma="2.2"
          name="Adobe RGB (1998)" />
...
</Image>

<Image ... >
...
   <RGBWorkingSpace x="0.648431:0.321152:0.155886"
          y="0.330856:0.597871:0.066044"
          Y="0.222491:0.716888:0.060621" gamma="sRGB"
          name="sRGB IEC61966-2.1" />
...
</Image>

<Image ... >
...
   <RGBWorkingSpace x="0.648431:0.230154:0.155886"
          y="0.330856:0.701572:0.066044"
          Y="0.333333:0.333333:0.333333" gamma="1"
          name="Uniform Linear with sRGB Primaries" />
...
</Image>

In the next example, an RGBWorkingSpace element has been defined somewhere in the XISF header with uid="SampleRGBWS", and has been associated with an image through a Reference element:

<Image ... >
...
   <Reference ref="SampleRGBWS" />
...
</Image>
...
<RGBWorkingSpace ... uid="SampleRGBWS" ... />

11.9.1 Mandatory DisplayFunction Attributes

These parameters shall be serialized by a DisplayFunction core element with the following required XML attributes:

m="m_RK:m_G:m_B:m_L"

m_RK, m_G, m_B and m_L are plain text representations of floating point numbers. The values of these attributes are, respectively, the midtones balance parameters for the red/gray, green, blue and lightness image components.

s="s_RK:s_G:s_B:s_L"

s_RK, s_G, s_B and s_L are plain text representations of floating point numbers. The values of these attributes are, respectively, the shadows clipping points for the red/gray, green, blue and lightness image components.

h="h_RK:h_G:h_B:h_L"

h_RK, h_G, h_B and h_L are plain text representations of floating point numbers. The values of these attributes are, respectively, the highlights clipping points for the red/gray, green, blue and lightness image components.

l="l_RK:l_G:l_B:l_L"

l_RK, l_G, l_B and l_L are plain text representations of floating point numbers. The values of these attributes are, respectively, the shadows dynamic range expansion parameters for the red/gray, green, blue and lightness image components.

r="r_RK:r_G:r_B:r_L"

r_RK, r_G, r_B and r_L are plain text representations of floating point numbers. The values of these attributes are, respectively, the highlights dynamic range expansion parameters for the red/gray, green, blue and lightness image components.

11.9.2 Optional DisplayFunction Attributes

The following attribute is optional for a DisplayFunction element:

name="df-name"

where df-name is an arbitrary sequence of Unicode characters that will be assigned as the name of the display function for identification purposes.

Example (some parts of the code replaced with ... to shorten the examples):

<Image ... >
...
   <DisplayFunction m="0.000735:0.000735:0.000735:0.5"
                    s="0.003758:0.003758:0.003758:0"
                    h="1:1:1:1"
                    l="0:0:0:0"
                    r="1:1:1:1"
                    name="AutoStretch" />
...
</Image>

In the next example, a DisplayFunction element has been defined somewhere in the XISF header with uid="AggressiveDF", and has been associated with an image through a Reference element:

<Image ... >
...
   <Reference ref="AggressiveDF" />
...
</Image>
...
<DisplayFunction ... uid="AggressiveDF" ... />

11.10.1 Mandatory ColorFilterArray Attributes

A ColorFilterArray core element shall define the following attributes:

pattern="p₁...p_N"

A sequence of characters defining the elements of a CFA matrix. Each p_i is a single ASCII character that represents an element of the CFA matrix, which can be one of:

Table 15
CFA pattern Elements

pattern character	CFA element
0	A nonexistent or undefined CFA element
R	Red
G	Green
B	Blue
W	White or panchromatic
C	Cyan
M	Magenta
Y	Yellow

The number N of p_i characters must be equal to the number of elements in the CFA matrix being described.

The represented matrix shall be oriented as it occurs on the image, and its elements shall be ordered from top to bottom and left to right. For example, in a 2x2 CFA, the first pattern element corresponds to the pixel at coordinates (x=0,y=0), the second pattern element to the pixel at (x=1,y=0), the third element to the pixel at (x=0,y=1), and the fourth element to the pixel at (x=1,y=1).

width="cfa-width"

cfa-width is a plain text representation of an unsigned integer whose value, which must be greater than zero, is the width in pixels of the CFA matrix.

height="cfa-height"

cfa-height is a plain text representation of an unsigned integer whose value, which must be greater than zero, is the height in pixels of the CFA matrix.

11.10.2 Optional ColorFilterArray Attributes

The following attribute is optional, but recommended, for ColorFilterArray core elements:

name="cfa-name"

cfa-name is a sequence of Unicode characters that must identify the type or model of CFA that is being described by the ColorFilterArray element.

Examples (some parts of the code replaced with ... to shorten the examples):

<Image ... >
...
   <ColorFilterArray pattern="GRBG" width="2" height="2" name="GRBG Bayer Filter" />
...
</Image>

<Image ... >
...
   <ColorFilterArray pattern="GBGGRGRGRBGBGBGGRGGRGGBGBGBRGRGRGGBG"
                        width="6" height="6" name="Fujifilm X-Trans Filter" />
...
</Image>

<Image ... >
...
   <ColorFilterArray pattern="GWRWWGWRBWGWWBWG"
                        width="4" height="4" name="Kodak TRUESENSE Sparse Color Filter" />
...
</Image>

In the next example, a ColorFilterArray element has been defined somewhere in the XISF header with uid="BGGR_Bayer_Filter", and has been associated with an image through a Reference element:

<Image ... >
...
   <Reference ref="BGGR_Bayer_Filter" />
...
</Image>
...
<Resolution ... uid="BGGR_Bayer_Filter" ... />

11.11.1 Mandatory Resolution Attributes

A Resolution core element shall define the following attributes:

horizontal="x-resolution"

x-resolution is a plain text representation of a floating point number, whose value must be greater than zero and shall be the resolution of the image in its X-axis (or horizontal axis), measured in pixels per resolution unit (see the unit attribute below).

vertical="y-resolution"

y-resolution is a plain text representation of a floating point number, whose value must be greater than zero and shall be the resolution of the image in its Y-axis (or vertical axis), measured in pixels per resolution unit (see the unit attribute below).

11.11.2 Optional Resolution Attributes

The following attribute is optional for a Resolution core element:

unit="resolution-unit"

resolution-unit defines the unit of length used to express image resolution values in the X and Y axes. resolution-unit must be one of:

inch

Image resolution shall be measured in pixels per inch.

cm

Image resolution shall be measured in pixels per centimeter.

When no unit attribute is specified, image resolution shall be expressed in pixels per inch by default.

Examples (some parts of the code replaced with ... to shorten the examples):

<Image ... >
...
   <Resolution horizontal="120" vertical="120" unit="cm" />
...
</Image>

In the next example, a Resolution element has been defined somewhere in the XISF header with uid="PrintingResolution", and has been associated with an image through a Reference element:

<Image ... >
...
   <Reference ref="PrintingResolution" />
...
</Image>
...
<Resolution ... uid="PrintingResolution" ... />

Examples (some parts of the code replaced with ... to shorten the examples):

<Image ... >
...
   <Thumbnail geometry="400:300:3"
              sampleFormat="UInt8" colorSpace="RGB" location="attachment:8192:360000" />
...
</Image>

In the next example, a Thumbnail element has been defined somewhere in the XISF header with uid="TheThumbnail", and has been associated with an image through a Reference element:

<Image ... >
...
   <Reference ref="TheThumbnail" />
...
</Image>
...
<Thumbnail uid="TheThumbnail" geometry="400:300:3"
           sampleFormat="UInt8" colorSpace="RGB" location="attachment:8192:360000" />