XISF Version 1.0 Specification (DRAFT 5)

1.1 Contributors

• Jean–Marc Lugrin (Switzerland)
• Mike Schuster (United States)
• Georg Viehoever (Germany)

1.2 Copyright Information

Copyright © 2014-2015 Pleiades Astrophoto S.L. All rights reserved.

This document may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to Pleiades Astrophoto S.L., except as needed for the purpose of developing any document or deliverable produced by Pleiades Astrophoto S.L.

The limited permissions granted above are perpetual and will not be revoked by Pleiades Astrophoto S.L. or its successors or assigns.

1.3 Disclaimer

This document and the information contained herein is provided on an "AS IS" basis and PLEIADES ASTROPHOTO S.L. DISCLAIMS ALL WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, ANY ACTUAL OR ASSERTED WARRANTY OF NON-INFRINGEMENT OF PROPRIETARY RIGHTS, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. NEITHER PLEIADES ASTROPHOTO S.L. NOR ITS CONTRIBUTORS SHALL BE HELD LIABLE FOR ANY IMPROPER OR INCORRECT USE OF INFORMATION. NEITHER PLEIADES ASTROPHOTO S.L. NOR ITS CONTRIBUTORS ASSUME ANY RESPONSIBILITY FOR ANYONE'S USE OF INFORMATION PROVIDED BY PLEIADES ASTROPHOTO S.L. IN NO EVENT SHALL PLEIADES ASTROPHOTO S.L. OR ITS CONTRIBUTORS BE LIABLE TO ANYONE FOR DAMAGES OF ANY KIND, INCLUDING BUT NOT LIMITED TO, COMPENSATORY DAMAGES, LOST PROFITS, LOST DATA OR ANY FORM OF SPECIAL, INCIDENTAL, INDIRECT, CONSEQUENTIAL OR PUNITIVE DAMAGES OF ANY KIND WHETHER BASED ON BREACH OF CONTRACT OR WARRANTY, TORT, PRODUCT LIABILITY OR OTHERWISE.

3.1 Requirement Levels

The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in RFC 2119.^[3]

3.2 Typographical Conventions

• Monospaced text represents literal source code fragments.
• Italicized monospace text represents metalanguage fragments describing source code elements:

  name="value"

  In this example, the word value is a metasymbol used to describe the value of a name XML attribute.

• In code fragments, an ellipsis represents a variable-length list of items:

  item₁:...:item_N

  This example shows a list of N items separated by literal colon ':' characters. Note that the item_i elements are metasymbols in this case, not literal fragments.

• Portions of this document enclosed by gray dashed lines represent literal source code examples:

           This is a source code example.

  Literal source code fragments do not necessarily correspond to working code examples. When necessary or not obvious, this is indicated in the text describing the examples.

• The subindexes _{2 8 10} and ₁₆ indicate base 2 (or binary), base 8 (octal), base 10 (decimal), and base 16 (hexadecimal) integers, respectively. For example:

  76₁₀ = 4C₁₆

• Figures are for illustration only; unless explicitly stated, they are not reference renderings.

7.1 Baseline XISF Encoder

A baseline XISF encoder shall have at least the following abilities to generate XISF units:

• Write monolithic XISF files.
• Write a single Image core element to a monolithic XISF file.
• Write pixel data as an XISF block with attachment block location.
• Write pixel data in the planar pixel storage model.
• Write pixel data in the UInt16 pixel sample format.
• Write pixel data encoded in the grayscale and RGB color spaces.

7.2 Baseline XISF Decoder

A baseline XISF decoder shall have at least the following abilities to read XISF units:

• Read monolithic XISF files.
• Read multiple Image core elements from a monolithic XISF file.
• Support zlib decompression.
• Read pixel data from XISF blocks with inline, embedded and attachment block locations.
• Read pixel data in the planar and normal pixel storage models.
• Read pixel data in the UInt8, UInt16 and Float32 pixel sample formats.
• Read pixel data encoded in the grayscale and RGB color spaces.

8.1 Fundamental Scalar Types

Table 2 lists the fundamental data types used to define all objects serializable by XISF. All of these types are fixed-length scalar data types.

Fundamental scalar types can be unsigned integer numbers, two's complement signed integer numbers, and floating point numbers. Floating point types correspond to the IEEE 754^[27] binary32 and binary64 basic formats, also known as single precision and double precision, respectively. For floating point types, the lower and upper bound columns in Table [2] refer to the approximate smallest and largest representable normal values, and the decimal precision column gives the relative rounding error for each type, also known as machine epsilon.

IEEE 754 non-numeric entities, including infinities and NaN (Not a Number), are supported by this specification and must be correctly handled (in an implementation-specific manner) by XISF encoders and decoders.

8.2 Endianness

All the data stored in an XISF unit, including XISF headers, XISF data blocks files and all XISF data blocks, shall be encoded as little-endian.

The only exception to this rule occurs when an object in another format requiring big endian encoding has to be embedded in an XISF unit. ICC color profiles^[29] are the most frequent instances of this exception.

The contents of external files not encoded as XISF data blocks, which can be referenced from distributed XISF unit headers, are out of the scope of this specification. Therefore, the endianness of these files and the way they are used are the responsibility of the decoders and applications accessing them.

8.3 Plain Text Serialization of Scalars

Serializations of scalar values as plain text—for example, in XML attribute values—shall comply with the following rules:

8.4 XISF Property

An XISF property is an association of two data structures, identifier and value. A property may also have an optional associated format specifier to control its representation as readable text. An XISF property may be associated, either with an object stored in an XISF unit, or with an XISF unit as a whole. An XISF property may also be stored in an XISF unit as a standalone object. Valid associations between properties and objects will be defined later in this document.

8.5 XISF Image

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.^[46]
• 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.^{[50] [39]}
• 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^[52] 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.
• Although the roles of alpha channels are implementation-defined, the first alpha channel, at index , should define the transparency of the image for alpha-compositing operations.^[55]
• Every real or integer image defines a visually representable numerical range, which we formalize as a representable range propery.

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

Figure 1 — Structure of a two-dimensional image.

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*.

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 ^[50], ^[52] and ^[56].

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.^[32]
• 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^[30] 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.^[28] 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,^[28] 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,^[28] 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]

8.5.4.6 RGB to Grayscale Conversion

A colorimetrically defined grayscale component shall be computed as the L* component of the CIE L*a*b* space.

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 display device able to generate image representations for input pixel sample values in the range. We call this range the device's input range, and we conventionally call and black and white, respectively. Pixel samples outside the input 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 display device so defined, the representable range of the image shall be applied for each pixel sample by means of the following algorithm:

[17]

This algorithm is a simple linear mapping of pixel sample values from the representable range of an image to a display 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 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 defined explicitly; see the bounds attribute of the Image core element for implementation-related information.

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 does not exist. The reason for this restriction is that a visually representable range, as we have described it with the above algorithm, does not really make sense 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 specification.

For color images encoded in a color space 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, where:

• 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 RGB color images.

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

[18]

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 ^[51] for evaluation of the diagonal rational function, given the three fixed points of the midtones transfer function.

Define the clipping function

[19]

and the expansion function

[20]

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

[21]

The identity display function is defined by the following parameters :

[22]

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 [18], [19] and [20], Equation [17] 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

9.1 XISF Unit

An XISF unit shall consist of a unique XISF header and zero or more XISF data blocks. Two storage models are supported and formally defined in this specification: monolithic and distributed:

• The contents of a monolithic XISF unit (Figure [5]) shall be stored in a single monolithic XISF file, which must include a unique XISF header and zero or more attached XISF data blocks.
• The contents of a distributed XISF unit (Figure [6]) 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.

The difference between the monolithic and distributed storage models is that a monolithic XISF unit must store the header and all of the data pertaining to the XISF unit in a single file, while a distributed XISF unit must store the header and the data separately in different files.

Figure 5 — Structure of a monolithic XISF unit.

Figure 6 — Structure of a distributed XISF unit.

9.2 Monolithic XISF File

A monolithic XISF file shall have the following structure:

Signature

A sequence of eight contiguous bytes whose values must form the set 'XISF0100' of ASCII characters,^[19] that is, the sequence 88₁₀ 73₁₀ 83₁₀ 70₁₀ 48₁₀ 49₁₀ 48₁₀ 48₁₀ of unsigned 8-bit integers.

Header length

An unsigned 32-bit integer whose value must be the length in bytes of the XISF header.

Reserved field

Four contiguous bytes reserved for future use. The values of these bytes shall be zero.

XISF header

The unique XISF header of the XISF unit.

Unused space (optional)

A sequence of zero or more contiguous bytes that may exist immediately after the XISF header. The bytes in an unused space must be zero.

Attached XISF data blocks (optional)

Zero or more attached XISF data blocks that may exist, either immediately after the XISF header, or after the optional unused space if it exists. Each attached data block is a sequence of one or more contiguous bytes. Attached data blocks may be separated by unused space, with the same definition as above.

Figure [7] shows a graphical representation of a monolithic XISF file. An XISF decoder or a file management application can use the XISF signature (the first eight bytes of the file) to quickly determine if a given file can be a valid monolithic XISF file. The header length field has the advantage that an XISF decoder can load the entire XISF header in memory using a single file read operation. Without the header length element, a decoder would have to scan the XML source code sequentially in order to find the end of the XISF header. Unused spaces can be useful to optimize I/O buffering and access to attached data blocks in some devices.

Figure 7 — Structure of a monolithic XISF file.

The following C++ code snippet shows a practical implementation of a structure to represent the initial components of a monolithic XISF file, including construction and validation.

#include <cstdint>

/*
 * Monolithic XISF file header.
 */
struct XISFMonolithicFileHeader
{
   uint8_t  magic[ 8 ];   // 'XISF0100'
   uint32_t headerLength; // length in bytes of the XML file header
   uint32_t reserved;     // reserved - must be zero

   /*
    * Constructs a monolithic XISF file header with the specified XML header
    * length in bytes.
    */
   XISFMonolithicFileHeader( uint64_t _headerLength )
   {
      magic[0] = 'X'; magic[1] = 'I'; magic[2] = 'S'; magic[3] = 'F';
      magic[4] = '0'; magic[5] = '1'; magic[6] = '0'; magic[7] = '0';
      headerLength = _headerLength;
      reserved = 0;
   }

   /*
    * Returns true if this is a valid monolithic XISF file header.
    */
   bool IsValid() const
   {
      return magic[0] == 'X' && magic[1] == 'I' && magic[2] == 'S' && magic[3] == 'F' &&
             magic[4] == '0' && magic[5] == '1' && magic[6] == '0' && magic[7] == '0' &&
             headerLength >= 65; // minimum length of an empty header from "<?xml..." to </xisf>
   }
};

9.3 XISF Header File

An XISF header file must contain exclusively the unique XISF header of a distributed XISF unit.

9.4 XISF Data Blocks File

An XISF data blocks file may contain zero or more XISF data blocks and may contain unused space, as described below. XISF data blocks files can be available as local or remote resources.

An XISF data blocks file shall have the following structure (Figure [8]):

Signature

A sequence of eight contiguous bytes whose values must form the set 'XISB0100' of ASCII characters,^[19] that is, the sequence 88₁₀ 73₁₀ 83₁₀ 66₁₀ 48₁₀ 49₁₀ 48₁₀ 48₁₀ of unsigned 8-bit integers.

Reserved field

Eight contiguous bytes reserved for future use. The values of these bytes shall be zero.

Block index

The block index of an XISF data blocks file is a singly linked list^{[47] [48] [49]} of block index nodes (Figure [9]). A block index node contains a sequence of block index elements. Each block index element may define the position and length of an XISF data block stored in the data blocks file.

A block index node shall have the following structure:

Length

An unsigned 32-bit integer whose value must be the number of block index elements available in this block index node.

Reserved field

Four contiguous bytes reserved for future use. The values of these bytes shall be zero.

Next node

An unsigned 64-bit integer whose value must be the byte position, measured from the beginning of the XISF data blocks file, of the next block index node. If the value of this element is zero, then this is the last block index node of the block index.

Elements

A sequence of contiguous block index elements. A block index element must define the position and length of an XISF data block stored in the XISF data blocks file. We say that a block index element points to the XISF data block whose position and length it defines.

A block index element shall be a sequence of 40 contiguous bytes with the following structure (Figure [10]):

Unique Identifier

An unsigned 64-bit integer. This identifier must be unique in the XISF data blocks file, that is, no two index elements can have the same identifier in a given data blocks file.

Block position

An unsigned 64-bit integer whose value must be the byte position, measured from the beginning of the XISF data blocks file, of the first byte of the XISF data block pointed to by the block index element.

The block position of a block index element may be zero. In such case the element is called a free block index element. A free block index element does not provide access to any data block, and can be used as a placeholder to access future data blocks that can be stored in the data blocks file.

Block length

An unsigned 64-bit integer whose value must be the length in bytes of the XISF data block pointed to by the block index element.

For free block index elements, the block length must be zero.

Uncompressed block length

An unsigned 64-bit integer. If the data block pointed to by the block index element has been compressed, the value of this item must be the length in bytes of the uncompressed data block.

For free block index elements and index elements pointing to uncompressed blocks, the uncompressed block length must be zero.

Reserved field

Eight contiguous bytes reserved for future use. The values of these bytes shall be zero.

XISF data blocks (optional)

Zero or more XISF data blocks, which may be stored in the XISF data blocks file. Each data block is a sequence of one or more contiguous bytes, whose position and length must be defined by at least one block index element pertaining to the block index of the XISF data blocks file.

Unused space (optional)

Since XISF data blocks can be stored at arbitrary locations in an XISF data blocks file, there may be sequences of zero or more contiguous bytes that don't pertain to any data block. These sequences collectively form the unused space of an XISF data blocks file. All bytes pertaining to the unused space must be zero.

Unused spaces can be useful to optimize I/O buffering and access to data blocks in some devices. They can also be useful as pre-allocated spaces for storage of new data blocks.

Figure [8] shows a graphical representation of an XISF data blocks file. An XISF decoder or a file management application can use the XISB signature (the first eight bytes of the file) to quickly determine if a given file can be a valid XISF data blocks file. Figure [9] represents the structure of a block index structure. Finally, Figure [10] outlines the structure of a block index element.

Figure 8 — Structure of an XISF data blocks file.

Figure 9 — Structure of an XISF block index.

Figure 10 — Structure of an XISF block index element.

The following C++ code snippet shows a practical implementation of a structure to represent the initial components of an XISF data blocks file, including construction and validation.

#include <cstdint>

/*
 * XISF data blocks file header.
 */
struct XISFDataBlocksFileHeader
{
   uint8_t  magic[ 8 ];   // 'XISB0100'
   uint64_t reserved;     // reserved - must be zero

   /*
    * Constructs a default XISF data blocks file header.
    */
   XISFDataBlocksFileHeader()
   {
      magic[0] = 'X'; magic[1] = 'I'; magic[2] = 'S'; magic[3] = 'B';
      magic[4] = '0'; magic[5] = '1'; magic[6] = '0'; magic[7] = '0';
      reserved = 0;
   }

   /*
    * Returns true if this is a valid XISF data blocks file header.
    */
   bool IsValid() const
   {
      return magic[0] == 'X' && magic[1] == 'I' && magic[2] == 'S' && magic[3] == 'B' &&
             magic[4] == '0' && magic[5] == '1' && magic[6] == '0' && magic[7] == '0';
   }
};

In the next code fragment we implement the XISF block index element structure with automatic generation of unique identifiers. The RandomUI64() static member function of XISFBlockIndexElement should be implemented to generate high-quality, pseudo-random uniform deviates as unsigned 64-bit integer values with a good random seeding routine. The XorShift1024* algorithm^{[53] [54] [57]} is recommended.

#include <cstdint>

/*
 * XISF block index element.
 */
struct XISFBlockIndexElement
{
   uint64_t uniqueId;                // unique block index element identifier
   uint64_t blockPosition;           // block byte offset from file beginning
   uint64_t blockLength;             // stored block length in bytes
   uint64_t uncompressedBlockLength; // uncompressed block length in bytes
   uint64_t reserved;                // reserved - must be zero

   /*
    * Constructs a free block index element.
    */
   XISFBlockIndexElement() : uniqueId( RandomUI64() )
   {
      blockPosition = blockLength = uncompressedBlockLength = reserved = 0;
   }

   /*
    * Returns true if this is a free block index element.
    */
   bool IsFree() const
   {
      return blockPosition == 0;
   }

private:

   /*
    * Returns a pseudo-random 64-bit unsigned integer.
    */
   static uint64_t RandomUI64()
   {
      ...
   }
};

9.5 XISF Header

An XISF header shall be a valid XML 1.0 document^[12] encoded in UTF-8^{[17] [18]}, with strict compliance of the syntax and properties described in this document. The functional roles of an XISF header shall be at least the following:

• Define a number of elements and properties describing an XISF unit as a whole.
• Define a number of elements and properties describing every object and data structure contained in an XISF unit.
• Define the location and length of every XISF data block stored in an XISF unit.

A valid XISF header shall have the following structure:

XML declaration

A valid XISF header must begin with the following XML declaration:

<?xml version="1.0" encoding="UTF-8"?>

Initial comment (recommended)

An XISF header should include a brief comment after the XML declaration. This initial comment should (1) specify that the XML document pertains to an XISF unit by declaring the XISF format and its version, and (2) identify the software which has created the XISF unit. The following example shows the starting lines of an XISF header with the XML declaration followed by a valid initial comment:

<?xml version="1.0" encoding="UTF-8"?>
<!--
Extensible Image Serialization Format - XISF version 1.0
Created with TheMagicImagingSoftware - http://reallymagic.com/
-->

An XISF encoder should replace "TheMagicImagingSoftware" and "http://reallymagic.com/" in the comment above with the name of the software application that has created the XISF unit and a relevant URL, respectively.

An XISF decoder must not rely on the information included in the initial comment of an XISF header to modify its behavior in any way.

XISF root element

The XISF root element is the top-level XML element that defines the entire contents of an XISF unit. A unique instance of the XISF root element shall be present in every XISF header, following the XML declaration and, when it exists, the initial comment. The XISF root element has the following properties:

• Its name shall be xisf and shall be interpreted as case-sensitive.
• Must have the version attribute, whose value shall be "1.0".
• Should have the following namespace^[13] and schema^[14] attributes:
  
  
  xmlns="http://www.pixinsight.com"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.pixinsight.com/xisf http://pixinsight.com/xsd/xisf-1.0.xsd"
• May have child XML elements describing the objects and data structures contained in an XISF unit.
• If the XISF unit contains some data structures or objects, then the XISF root element must have the necessary child elements to describe them.
• Must not have character data contents.

The following example shows the initial lines of a valid XISF header with the start-tag of its XISF root element:

<?xml version="1.0" encoding="UTF-8"?>
<!--
Extensible Image Serialization Format - XISF version 1.0
Created with TheMagicImagingSoftware - http://reallymagic.com/
-->
<xisf version="1.0"
   xmlns="http://www.pixinsight.com"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.pixinsight.com/xisf http://pixinsight.com/xsd/xisf-1.0.xsd">

XISF child elements (optional)

XISF child elements are child XML elements of the unique XISF root element in an XISF header. XISF child elements shall describe data structures and objects stored in an XISF unit. A reduced number of XISF child elements have been formalized in this specification to support essential data structures; we call these elements XISF core elements.

XISF is an extensible format mainly because new child elements may be defined as necessary to describe new data structures and objects stored in XISF units, which have not been formalized in this specification.

XML signature (optional)

After the XISF root element, an XML signature^[15] may be included to provide data integrity and authentication. The signed data shall be the XISF root element and its entire contents, including the whole XML tree: All child XML elements of the root element and their contents.

If the XISF unit is digitally signed with an XML signature, then the checksum attribute must be included and correctly implemented for every data block not serialized directly in the XISF header, including all blocks with attachment, url, absolute path and relative path block locations. With a digital signature and data checksums correctly implemented, a signed XISF unit effectively seals all of its contents and guarantees data integrity.

The XML signature of an XISF unit must be implemented as a detached signature in the header XML document. The XISF root element, which shall be the object being signed, must be specified through an id attribute in the Reference element of the signature. The following example clarifies these concepts (some parts of the code replaced with ... to shorten the example):

<?xml version="1.0" encoding="UTF-8"?>
<!--
Extensible Image Serialization Format - XISF version 1.0
Created with TheMagicImagingSoftware - http://reallymagic.com/
-->
<xisf version="1.0" id="XISFRootElement"
   xmlns="http://www.pixinsight.com"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.pixinsight.com/xisf http://pixinsight.com/xsd/xisf-1.0.xsd">
   ...
   ...
   ...
</xisf>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
   <CanonicalizationMethod Algorithm="http://www.w3.org/2006/12/xml-c14n11"/>
   <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/>
   <Reference URI="#XISFRootElement">
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
      <DigestValue>...</DigestValue>
   </Reference>
</SignedInfo>
<SignatureValue>...</SignatureValue>
<KeyInfo>
   <KeyValue>
      <RSAKeyValue>
         <Modulus>...</Modulus>
         <Exponent>...</Exponent>
      </RSAKeyValue>
   </KeyValue>
   <X509Data>
      <X509SubjectName>...</X509SubjectName>
      <X509IssuerSerial>
         <X509IssuerName>...</X509IssuerName>
         <X509SerialNumber>...</X509SerialNumber>
      </X509IssuerSerial>
      <X509Certificate>...</X509Certificate>
   </X509Data>
</KeyInfo>
</Signature>

In this example, the XISF root element being signed is selected with the "XISFRootElement" identifier through a same-document reference.^[6] The root element is signed with a SHA-1 digest^[4] and the RSA public key of an X.509 certificate.^[9]

9.6 File Name Suffixes

The following file name suffixes, also known as file name extensions in some operating systems, are mandatory for files pertaining to XISF units:

• Monolithic XISF files must carry the .xisf file name suffix.
• XISF header files must carry the .xish file name suffix.
• XISF data blocks files shall carry the .xisb file name suffix.

10.1 Attached XISF Data Block

An attached XISF data block is an XISF data block stored in a monolithic XISF file.

The position of an attached data block from the beginning of the monolithic XISF file where it is stored, as well as its length in bytes, must be completely and unambiguously defined by the XISF header of the XISF unit.

10.2 External XISF Data Block

An external XISF data block is an XISF data block stored separately from the XISF header of a distributed XISF unit. An external XISF data block can be stored either in an XISF data blocks file, or in a generic file.

The position of an external data block and its length in bytes must be completely and unambiguously defined by the XISF header and, when applicable, by the XISF data blocks file where the block is stored.

10.3 XISF Data Block Location

The location—and, when necessary, also the dimensions—of an XISF data block must be completely defined in the XISF header of the XISF unit where the block is serialized. The location XML attribute defines the location of an XISF data block and a number of related properties. The values of a location attribute can be:

location="inline:encoding"

Defines an inline XISF data block. An inline data block is serialized in the character contents of an XML element, encoded as plain ASCII^[19] text. encoding defines the data encoding used, which must be either base64 or hex, corresponding to the Base64 and Base16 (or hexadecimal) encodings,^[8] respectively. For data encoded in Base16, the digit symbols 'a', 'b', 'c', 'd', 'e' and 'f' shall be used to represent the nibble values 10₁₀, 11₁₀, 12₁₀, 13₁₀, 14₁₀ and 15₁₀, respectively; in other words, a lowercase hexadecial representation shall be used for Base16 encoding.

Example of inline XISF data block:

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

Note that white space is irrelevant and must be ignored for Base64 and Base16 encoded data.

XML elements serializing inline XISF data blocks shall not have child XML elements.

location="embedded"

Defines an embedded XISF data block. An embedded block shall be serialized in the character contents of a Data child element, encoded as plain ASCII^[19] text. The Data child element must have an encoding attribute, with the same meaning and rules as for inline data blocks.

Example of embedded XISF data block:

<Image geometry="6:6:3" sampleFormat="UInt8" colorSpace="RGB" location="embedded">
   <Data encoding="base64">
      AAAAAP8A/wD/AAAAAAAAAP8AAP8AAAAAAAAA/wD/AP8AAAAA/wD//wD/AP8AAP8A/wD//wD//
      wD//wD/AP8AAP8A/wD//wD/AP8AAAAAAAAA/wD/AP8AAAAAAAAAAP8A/wD/AAAAAAAAAP8A
   </Data>
</Image>

Note that white space is irrelevant and must be ignored for Base64 and Base16 encoded data.

The Data child element serializing an embedded data block shall not have child elements or additional character data contents.

Embedded data blocks are necessary for blocks that have to be serialized within XML elements that can have child elements or character data contents. In these cases an inline serialization is forbidden by this specification.

location="attachment:position:size"

Defines an attached XISF data block in a monolithic XISF file. position and size must be plain text representations of unsigned integers. The value of position is the byte position of the first byte of the XISF data block from the beginning of the monolithic XISF file where it is stored. The value of size is the size in bytes of the XISF data block.

Example of attached XISF data block:

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

location="url(URL)"
location="url(URL):index-id"

Defines an external XISF data block in a distributed XISF unit.

URL must be a valid uniform resource locator^[6] specification for a local or remote file where the XISF data block should be available.

In the first form, the data block shall start at byte position zero of the specified file, and its size in bytes must be the total size of the specified file, whose value must be retrievable by some means that are beyond the scope of this specification; for example, by reading the properties of a local directory entry, or by fetching the total length of the data downloaded from a remote server.

In the second form, the specified file must be an XISF data blocks file. index-id must be a plain text representation of an unsigned integer, whose value must be the unique identifier of a block index element in the XISF data blocks file. index-id should be represented as an hexadecimal number. The referenced block index element must define the position and size of the XISF data block being located.

Example of external XISF data block stored on a remote server:

<Image geometry="4096:4096:1" sampleFormat="UInt16"
                  location="url(http://mysite.example.com/myfile.bin)" />

Example of XISF data block stored in an XISF data blocks file:

<Property id="AHugeOne" type="F32Matrix" rows="100000" columns="25000"
                  location="url(file:///data/huge-things.xisb):0x7a73526b584c6167" />

Parentheses appearing in a URL must be written as percent-encoded octets,^[6] so that the resulting location attribute value can be parsed correctly. For example:

<Property id="FooMatrix" type="Matrix" rows="12345" columns="54321"
                  location="url(ftp://ftp.example.com/public/example%282015%29.dat)" />

In the above example the file name being referenced is "example(2015).dat".

location="path(abs-file-path)"
location="path(abs-file-path):index-id"

Defines an external XISF data block stored in a local file with an absolute file path specification.

abs-file-path is an absolute path^[24] to a file located on, or accessible from, the local file system. File path specifications shall follow standard UNIX pathname syntax rules^[22] and pathname resolution^[23] on all platforms. In particular, only slash characters ('/', ASCII code point 47₁₀ = 2F₁₆) shall be used as directory separators.

In the first form, the data block shall start at byte position zero of the specified file, and its size in bytes must be the total size of the file, whose value must be retrievable by some means that are beyond the scope of this specification; for example, by reading the properties of a local directory entry.

In the second form, the specified file must be an XISF data blocks file. index-id must be a plain text representation of an unsigned integer, whose value must be the unique identifier of a block index element in the XISF data blocks file. index-id should be represented as an hexadecimal number. The referenced block index element must define the position and size of the XISF data block being located.

In general, absolute paths are not recommended and should be avoided, since they tend to prevent distributed XISF units from being relocatable. If a unit with absolute path names is moved or copied to a different file system or machine, it will cease to be valid unless the original directory tree exists on the target file system.

In some special cases, however, absolute paths can be useful. For example, a virtualized file system can be based on absolute paths to symbolic links^[26] pointing to actual directories. In this case a distributed XISF unit with absolute paths to external resources can be made relocatable by emulating the required directory tree structure through symbolic links on the deployment file system.

Parentheses appearing in a path specification must be escaped with a backslash ('\', ASCII code point 92₁₀ = 5C₁₆), so that the resulting location attribute value can be parsed correctly. For example:

<Property id="DescriptionDocument" type="String"
                  location="path(/Documents/description\(draft\).txt)" />

location="path(@header_dir/rel-file-path)"
location="path(@header_dir/rel-file-path):index-id"

Defines an external XISF data block stored in a local file with a relative directory path specification.

rel-file-path is a path to a file, relative^[25] to the directory where the file containing the XISF header is located on, or accessible from, the local file system. Directory path specifications shall follow standard UNIX pathname syntax rules^[22] and pathname resolution^[23] on all platforms. In particular, only slash characters ('/', ASCII code point 47₁₀ = 2F₁₆) shall be used as directory separators.

In the first form, the data block shall start at byte position zero of the specified file, and its size in bytes must be the total size of the file, whose value must be retrievable by some means that are beyond the scope of this specification; for example, by reading the properties of a local directory entry.

In the second form, the specified file must be an XISF data blocks file. index-id must be a plain text representation of an unsigned integer, whose value must be the unique identifier of a block index element in the XISF data blocks file. index-id should be represented as an hexadecimal number. The referenced block index element must define the position and size of the XISF data block being located.

The following Image element shows an example of XISF data block located with a relative directory specification. The sample-screenshots.xisb data blocks file should be on the same directory as the XISF header file being decoded:

<Image geometry="1024:768:3" sampleFormat="UInt8" colorSpace="RGB"
                  location="path(@header_dir/sample-screenshots.xisb):0x4d373e33756e480f" />

The following example assumes that an astrometry sub-directory exists on the local directory represented by @header_dir:

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

As happens with absolute path locations, parentheses appearing in a relative path specification must be escaped with a backslash ('\', ASCII code point 92₁₀ = 5C₁₆), so that the resulting location attribute value can be parsed correctly:

<Property id="DescriptionDocument" type="String"
                  location="path(@header_dir/description\(draft\).txt)" />

Relative file paths are the best option to build relocatable distributed XISF units. A distributed unit that locates all of its external data blocks through relative paths can be transferred to any location on any file system, including multiple machines, without breaking its validity. This can't be ensured for blocks located by absolute paths.

10.4 XISF Data Block Checksum

XML elements serializing XISF data blocks can include a checksum attribute to enforce data integrity with a cryptographic hashing algorithm.

If the XISF unit is digitally signed with an XML signature, then the checksum attribute must be included and correctly implemented for every data block not serialized directly in the XISF header, including all blocks with attachment, url, absolute path and relative path block locations.

Cryptographic checksums are optional for non-signed units, although their implementation is recommended for all XISF encoders as a user-selectable option available in all cases, irrespective of digital signatures.

When a checksum attribute is defined for an XML element serializing a data block, an XISF decoder must verify it by computing a new digest from the serialized data and comparing it with the value of the corresponding checksum attribute. If the digests differ, a decoder should issue a warning or error message and give the user an option to stop loading the affected data block or the entire XISF unit, as appropriate. This validation process must always occur before making the data block available to the user, either directly or indirectly. Checksum verification may be implemented on an on-demand basis: only data blocks whose contents have to be loaded from the XISF unit need to be verified. For unattented operations such as batch processes, a decoder should not load an XISF unit for which a checksum verification fails.

See also the section on compressed XISF data blocks for important security considerations about checksums and compression.

The syntax of the checksum attribute is as follows:

checksum="algorithm:digest"

where algorithm is a cryptographic hashing algorithm, and digest is the corresponding message digest computed for the entire contents of the XISF data block being serialized.

Message digests shall be encoded in Base16 using the lowercase hexadecimal digits 'a', 'b', 'c', 'd', 'e', and 'f'.

Supported algorithms include:

Table 9
Cryptographic Hashing Algorithms

Algorithm	checksum algorithm value	Alternate algorithm value
SHA-1[4]	sha-1	sha1
SHA-256[11]	sha-256	sha256
SHA-512[11]	sha-512	sha512
SHA3-256 (Keccak)[36] [58]	sha3-256
SHA3-512 (Keccak)[36] [58]	sha3-512

SHA-1 is the recommended general-purpose hashing algorithm for use in XISF units.

Example:

<Image geometry="4096:4096:1" sampleFormat="Float32" bounds="0:1"
       location="attached:134217728:67108864"
       checksum="sha1:97b25345e3bd74bcd6613d24e3ecb47617a31d20" />

10.5 XISF Data Block Compression

An XISF data block may be transformed with a compression codec or algorithm. Both lossless and lossy compression schemes are permitted. XML elements serializing the values of compressed XISF data blocks must include a compression XML attribute with the following syntax:

compression="codec:parameters"

where codec is the name of a compression algorithm, and parameters is a set of algorithm-dependent parameters. The value of the compression attribute must be sufficient to recover meaningful data for the XISF data block being serialized. Note that we specify meaningful instead of the original because lossy compression algorithms are supported. The performance and ability of a compression algorithm to maximize compression ratios and minimize data degradation are beyond the scope of this specification.

For embedded XISF data blocks, the compression attribute shall be an attribute of the Data child element serializing the block's contents, not of the element that serializes the block. For the rest of block location modes, the compression attribute shall be included in the element that serializes the block.

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

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

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

11.1 Property Core Element

The Property core element has the following properties:

• A Property element shall serialize an XISF property.
• An XISF header may contain multiple Property core elements.
• A Property element may be a child element of a Metadata core element to serialize a property of the XISF unit.
• A Property element may be a child element of an Image core element to serialize a property of an XISF image.
• A Property element may be a child element of the unique XISF root element to serialize a standalone property.
• A Property element can be associated with Metadata or Image core elements by means of a uid attribute and child Reference elements.

<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" />

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

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

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

<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)" />

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

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

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

11.2 Metadata Core Element

The Metadata core element serializes a set of XISF properties to describe an XISF unit. Metadata properties must be serialized with child Property elements.

The identifiers of all Metadata properties have the 'XISF:' namespace prefix. These properties—including mandatory and optional properties—have reserved identifiers that must not be used for purposes different from the ones described herein.

A unique Metadata element shall be included in every XISF header as a child element of the XISF root element. The Metadata element must contain Property child 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>

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
FreeBSD	FreeBSD
Linux	Linux
Apple OS X	OS X
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 algorithm(s) used. If more than one algorithm has been used, they should be specified as a comma-separated list.

Example:

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

XISF:CompressionLevel

An Int32 property. If the XISF unit contains data blocks compressed with the standard zlib method,^[1] this property should be defined to specify the compression level used. Zlib's compression level is an integer parameter in the range from 0 to 9 that controls the speed/compression balance.

Example:

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

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.3 Image Core Element

The Image core element defines an XISF image serialized in an XISF unit. Image elements shall be child elements of the unique XISF root element of the XISF unit.

The entire pixel data contents of an XISF image shall be serialized as a single XISF data block. An Image element cannot serialize pixel data as an inline XISF data block, this restriction obeying to the fact that Image elements can have child XML elements.

An Image element can have the following attributes:

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[27] 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 pixel data, and must not be specified for complex images.

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 mandatory for floating point real images, that is, 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, the 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 the 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 must not be specified, since the representable range property does not exist for these images. Visual representation of complex-valued pixel data is left as implementation-defined by this specification.

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

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.

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

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 12
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.

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.

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 14
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).

cfaType="cfa-spec"

This attribute should be specified for Image elements serializing images mosaiced with a Color Filter Array (CFA)^[37], such as a Bayer filter. ^{[38] [42]} This attribute shall not be specified for images not mosaiced with a CFA.

The supported cfaType attribute values are:

Table 15
cfaType Attribute Values

Color filter array	cfaType attribute value
RGGB Bayer filter	RGGB
BGGR Bayer filter	BGGR
GRBG Bayer filter	GRBG
GBRG Bayer filter	GBRG
CYGM (cyan/yellow/green/magenta) filter	CYGM
Fujifilm X-Trans filter	XTrans

Figure 11 — Color filter arrays (CFA) supported by the XISF 1.0 specification.

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:^[20]

[_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^{[53] [54] [57]} 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" />

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 supporting 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.

11.4 FITSKeyword Core Element

The FITSKeyword core element defines a FITS header keyword^[44] and associates it with an XISF image serialized in an XISF unit.

The contents of a FITSKeyword core element (i.e., the values of its name, value and comment attributes; see below) must comply with the requirements of the FITS format specification^[43] for header keywords.

A FITSKeyword core element shall define the following attributes:

name="keyword-name"

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

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.^[44] 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.^[44]

A FITSKeyword element must be either a child element of an Image core element, or a child element of the unique XISF root element. In the former case, the FITS header keyword shall be associated with the corresponding image. In the latter case, a uid attribute should be defined to associate the FITS header keyword with one or more Image elements by means of child Reference elements.

Multiple instances of the FITSKeyword element, and/or multiple Reference elements referencing existing FITSKeyword elements, can be children of an Image element to define a list of FITS keywords associated with an image.

The FITSKeyword element provides a compatibility layer with image data stored as legacy FITS files. An XISF decoder compatible with FITS must load all existing FITSKeyword elements and give access to them transparently, as if the original data were stored in the FITS format.

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" ... />

11.5 ICCProfile Core Element

The ICCProfile core element defines an ICC color profile^{[29] [31]} serialized in an XISF unit.

ICC color profiles shall be serialized as XISF data blocks storing ICC profile structures.

An ICCProfile element must be either a child element of an Image core element, or a child element of the unique XISF root element. In the former case, the ICC profile shall be associated with the corresponding image. In the latter case, a uid attribute should be defined to associate the ICC profile with one or more Image elements by means of child Reference elements.

The embedded profile flag (see Section 7.2.11 of the ICC profile specification^[29]) of an ICC profile stored in an XISF unit must be set to one to signify that the profile has been embedded in a file.

Note that the ICC profile specification states that all profile data shall be encoded as big-endian (Section 7 of the ICC profile specification^[29]). This implies that an XISF data block storing an ICC profile structure is an exception to the native little-endian encoding of XISF.

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.6 RGBWS Core Element

The RGBWS core element defines the parameters of a colorimetrically-defined RGB working color space (RGBWS) and associates it with an XISF image serialized in an XISF unit. From the referenced section, recall that the parameters of an RGBWS are:

Reference white

All RGB working space parameters defined in an XISF unit shall be relative to the standard D50 reference white.^[32]

Gamma exponent.

Chromaticity coordinates of the RGB primaries, normalized to the [0,1] range.

Luminance coefficients of the RGB primaries, normalized to the [0,1] range.

These parameters shall be serialized by an RGBWS core element with the following mandatory 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^[28] 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.

The following attribute is optional for an RGBWS element:

name="rgbws-name"

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

An RGBWS element must be either a child element of an Image core element, or a child element of the unique XISF root element. In the former case, the RGBWS shall be associated with the corresponding image. In the latter case, a uid attribute should be defined to associate the RGBWS with one or more Image elements by means of child Reference elements.

When no RGBWS element is specified for an Image core element, the default RGBWS shall be the sRGB space.^[28]

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

<Image ... >
...
   <RGBWS 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 ... >
...
   <RGBWS 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 ... >
...
   <RGBWS 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 RGBWS 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>
...
<RGBWS ... uid="SampleRGBWS" ... />

11.7 DisplayFunction Core Element

The DisplayFunction core element defines the parameters of a display function (DF) and associates it with an XISF image serialized in an XISF unit. From the referenced section, recall that the parameters of a DF are:

Vector of midtones balance parameters.

Vector of shadows clipping point parameters.

Vector of highlights clipping point parameters.

Vector of shadows dynamic range expansion parameters.

Vector of highlights dynamic range expansion parameters.

These parameters shall be serialized by a DisplayFunction core element with the following mandatory 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.

The following attribute is optional for a DisplayFunction element:

name="df-name"

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

A DisplayFunction element must be either a child element of an Image core element, or a child element of the unique XISF root element. In the former case, the DF shall be associated with the corresponding image. In the latter case, a uid attribute should be defined to associate the DF with one or more Image elements by means of child Reference elements.

When no DisplayFunction element is specified for an Image core element, the default DF shall be the identity display function (Equation [22]).

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.8 Resolution Core Element

The Resolution core element defines the data necessary to control the resolution of an XISF image stored in an XISF unit. Resolution defines the amount of pixels represented per unit of surface on a display medium, such as a printer or a computer monitor, and can be measured either in pixels per inch or in pixels per centimeter.

A Resolution core element shall define the following mandatory 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).

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.

A Resolution element must be either a child element of an Image core element, or a child element of the unique XISF root element. In the former case, the resolution parameters shall be associated with the corresponding image. In the latter case, a uid attribute should be defined to associate the resolution parameters with one or more Image elements by means of child Reference elements.

When no Resolution element is specified for an Image core element, the default image resolution shall be 72.0 pixels per inch.

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" ... />

11.9 Thumbnail Core Element

The Thumbnail core element defines a thumbnail image and associates it with an XISF image serialized in an XISF unit. A thumbnail is a two-dimensional image of relatively small dimensions providing a significant representation of a larger image. Typically, thumbnails are loaded by file browser applications to generate quick graphical previews of images stored in disk files.

A thumbnail image shall be serialized as an XISF image with the following properties:

• Two-dimensional image.
• UInt8 or UInt16 sample format.
• RGB or grayscale color space.
• Its width and height must not be greater than 1024 pixels.
• Can have a single alpha channel.

Other than its tag name, a Thumbnail core element is identical to an Image core element, with the following restrictions:

• The bounds attribute must not be defined. This implies that the representable range of a thumbnail image is always [0,2ⁿ–1], where n is either 8 or 16 bits.
• The cfaType attribute must not be defined. This implies that thumbnail images associated with mosaiced images should be already demosaiced versions.
• A child Thumbnail element shall not be present, that is, nested Thumbnail elements are not permitted.
• A child Reference element referencing a Thumbnail element shall not be present, for the same reason as above.

A Thumbnail core element must be either a child element of an Image core element, or a child element of the unique XISF root element. In the former case, the thumbnail shall be associated with the corresponding image. In the latter case, a uid attribute should be defined to associate the thumbnail with one or more Image elements by means of child Reference elements.

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" />

11.10 Reference Core Element

The Reference core element associates an XISF core element with a data object serialized in an XISF unit.

A Reference core element shall define a unique XML attribute, namely:

ref="unique-elem-id"

where unique-elem-id is the unique element identifier of an existing XISF core element, which must be defined in the same XISF unit. unique-elem-id shall be the value of the uid attribute of the referenced XISF core element.

Note that the Reference element is the only XISF core element that cannot have a uid attribute. This obeys to the fact that chained references, that is, references to references, are not permitted in this specification.

Reference core elements should be used, when possible, to prevent duplicate object serializations in XISF units. Reference elements can also be used to reduce the volume of markup required to associate a core element with several objects, and/or to improve structuration of XISF headers. Consider an example where three images have been serialized as follows:

<Image id="IMG7953" geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                              colorSpace="RGB" location="attachment:4096:268435456">
   <RGBWS 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 id="IMG7954" geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                              colorSpace="RGB" location="attachment:268439552:268435456">
   <RGBWS 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 id="IMG7955" geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                              colorSpace="RGB" location="attachment:536875008:268435456">
   <RGBWS 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>

As you see, the three images have been associated with identical RGB working spaces. Instead of repeating the same RGBWS element three times, we can simplify the markup considerably with Reference elements:

<Image id="IMG7953" geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                              colorSpace="RGB" location="attachment:4096:268435456">
   <Reference ref="RGBWS001" />
</Image>
<Image id="IMG7954" geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                              colorSpace="RGB" location="attachment:268439552:268435456">
   <Reference ref="RGBWS001" />
</Image>
<Image id="IMG7955" geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                              colorSpace="RGB" location="attachment:536875008:268435456">
   <Reference ref="RGBWS001" />
</Image>
<RGBWS uid="RGBWS001"
       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)" />

Let's put a slightly less evident example:

<?xml version="1.0" encoding="UTF-8"?>
<!--
Extensible Image Serialization Format - XISF version 1.0
Created with TheMagicImagingSoftware - http://reallymagic.com/
-->
<xisf version="1.0"
   xmlns="http://www.pixinsight.com"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.pixinsight.com/xisf http://pixinsight.com/xsd/xisf-1.0.xsd">

   <Image geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                                 colorSpace="RGB" location="attachment:4096:268435456" />
   <Image geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                                 colorSpace="RGB" location="attachment:4096:268435456" />
   <Image geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                                 colorSpace="RGB" location="attachment:4096:268435456" />
   <Image geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                                 colorSpace="RGB" location="attachment:4096:268435456" />
   ...
   ...
   ...
</xisf>

In the above example we have four images serialized in an XISF header. Note that these images are identical; in fact, all of them have been serialized as the same attached XISF data block (see the location attributes), so fortunately there is no quadruplication of pixel data. However, the markup clearly leaves room for improvement. The same result can be achieved with Reference elements in a much cleaner way:

<?xml version="1.0" encoding="UTF-8"?>
<!--
Extensible Image Serialization Format - XISF version 1.0
Created with TheMagicImagingSoftware - http://reallymagic.com/
-->
<xisf version="1.0"
   xmlns="http://www.pixinsight.com"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.pixinsight.com/xisf http://pixinsight.com/xsd/xisf-1.0.xsd">

   <Image uid="foo_bar"
          geometry="4096:4096:4" sampleFormat="Float32" bounds="0:1"
                                 colorSpace="RGB" location="attachment:4096:268435456" />
   <Reference ref="foo_bar" />
   <Reference ref="foo_bar" />
   <Reference ref="foo_bar" />
   ...
   ...
   ...
</xisf>