CdIt8: colord Reference Manual

## CdIt8 CdIt8 — Read and write IT8 color sample exchange files |

## Functions

GQuark | cd_it8_error_quark ()
CdIt8 * | cd_it8_new ()
CdIt8 * | cd_it8_new_with_kind ()
gboolean | cd_it8_load_from_data ()
gboolean | cd_it8_load_from_file ()
gboolean | cd_it8_save_to_file ()
gboolean | cd_it8_save_to_data ()
void | cd_it8_set_kind ()
void | cd_it8_set_normalized ()
void | cd_it8_set_originator ()
void | cd_it8_set_title ()
void | cd_it8_set_spectral ()
void | cd_it8_set_instrument ()
void | cd_it8_set_reference ()
void | cd_it8_set_enable_created ()
void | cd_it8_add_data ()
void | cd_it8_add_option ()
void | cd_it8_set_matrix ()
void | cd_it8_set_spectrum_array ()
void | cd_it8_add_spectrum ()
const CdMat3x3 * | cd_it8_get_matrix ()
CdIt8Kind | cd_it8_get_kind ()
gboolean | cd_it8_get_normalized ()
const gchar * | cd_it8_get_originator ()
const gchar * | cd_it8_get_title ()
gboolean | cd_it8_get_spectral ()
const gchar * | cd_it8_get_instrument ()
const gchar * | cd_it8_get_reference ()
gboolean | cd_it8_get_enable_created ()
guint | cd_it8_get_data_size ()
gboolean | cd_it8_get_data_item ()
GPtrArray * | cd_it8_get_spectrum_array ()
CdSpectrum * | cd_it8_get_spectrum_by_id ()
gboolean | cd_it8_has_option ()
CdColorXYZ * | cd_it8_get_xyz_for_rgb ()

## Properties

gchar * | instrument | Read
guint | kind | Read / Write
gboolean | normalized | Read
gchar * | originator | Read
gchar * | reference | Read
gboolean | spectral | Read
gchar * | title | Read

## Types and Values

#define | CD_IT8_ERROR
#define | CD_IT8_TYPE_ERROR
#define | CD_TYPE_IT8
struct | CdIt8Class
enum | CdIt8Error
enum | CdIt8Kind
| CdIt8

## Object Hierarchy

        GObject
        ╰── CdIt8

## Description

This object represents .ti1 and .ti3 files which can contain raw or normalized sample data.

## Functions

### cd_it8_error_quark ()

    GQuark
    cd_it8_error_quark (void);

#### Returns

An error quark.

Since: 0.1.0

### cd_it8_new ()

    CdIt8 *
    cd_it8_new (void);

Creates a new CdIt8 object.

#### Returns

a new CdIt8 object.

Since: 0.1.20

### cd_it8_new_with_kind ()

    CdIt8 *
    cd_it8_new_with_kind (CdIt8Kind kind);

Creates a new CdIt8 object.

#### Parameters

kind | a CdIt8Kind, e.g `CD_IT8_KIND_TI3`. |

#### Returns

a new CdIt8 object.

Since: 0.1.20

### cd_it8_load_from_data ()

    gboolean
    cd_it8_load_from_data (CdIt8 *it8,
                           const gchar *data,
                           gsize size,
                           GError **error);

Loads a it8 file from data.

#### Parameters

it8 | a CdIt8 instance. |
data | text data |
size | the size of text data |
error | a GError, or `NULL` |

#### Returns

`TRUE` if a valid it8 file was read.

Since: 0.1.20

### cd_it8_load_from_file ()

    gboolean
    cd_it8_load_from_file (CdIt8 *it8,
                           GFile *file,
                           GError **error);

Loads a it8 file from disk.

#### Parameters

it8 | a CdIt8 instance. |
file | a GFile |
error | a GError, or `NULL` |

#### Returns

`TRUE` if a valid it8 file was read.

Since: 0.1.20

### cd_it8_save_to_file ()

    gboolean
    cd_it8_save_to_file (CdIt8 *it8,
                         GFile *file,
                         GError **error);

Saves a it8 file to disk

#### Parameters

it8 | a CdIt8 instance. |
file | a GFile |
error | a GError, or `NULL` |

#### Returns

`TRUE` if it8 file was saved.

Since: 0.1.20

### cd_it8_save_to_data ()

    gboolean
    cd_it8_save_to_data (CdIt8 *it8,
                         gchar **data,
                         gsize *size,
                         GError **error);

Saves a it8 file to an area of memory.

#### Parameters

it8 | a CdIt8 instance. |
data | a pointer to returned data |
size | size of `data` |
error | a GError, or `NULL` |

#### Returns

`TRUE` if it8 file was saved.

Since: 0.1.26

### cd_it8_set_kind ()

    void
    cd_it8_set_kind (CdIt8 *it8,
                     CdIt8Kind kind);

Set the kind of IT8 file.

#### Parameters

it8 | a CdIt8 instance. |
kind | a CdIt8Kind, e.g `CD_IT8_KIND_TI3`. |

Since: 0.1.20

### cd_it8_set_normalized ()

    void
    cd_it8_set_normalized (CdIt8 *it8,
                           gboolean normalized);

Sets if normalized data should be written to the .it8 file.

#### Parameters

it8 | a CdIt8 instance. |
normalized | If the data is normalized |

Since: 0.1.20

### cd_it8_set_originator ()

    void
    cd_it8_set_originator (CdIt8 *it8,
                           const gchar *originator);

Sets the program name that created the .it8 file

#### Parameters

it8 | a CdIt8 instance. |
originator | the program name, e.g. "gcm-calibrate" |

Since: 0.1.20

### cd_it8_set_title ()

    void
    cd_it8_set_title (CdIt8 *it8,
                      const gchar *title);

Sets the display name for the file.

#### Parameters

it8 | a CdIt8 instance. |
title | the title name, e.g. "Factory calibration" |

Since: 0.1.20

### cd_it8_set_spectral ()

    void
    cd_it8_set_spectral (CdIt8 *it8,
                         gboolean spectral);

Sets if spectral data should be written to the .it8 file.

#### Parameters

it8 | a CdIt8 instance. |
spectral | If the data is spectral |

Since: 0.1.20

### cd_it8_set_instrument ()

    void
    cd_it8_set_instrument (CdIt8 *it8,
                           const gchar *instrument);

Sets the measuring instrument that created the .it8 file

#### Parameters

it8 | a CdIt8 instance. |
instrument | the instruemnt name, e.g. "huey" |

Since: 0.1.20

### cd_it8_set_reference ()

    void
    cd_it8_set_reference (CdIt8 *it8,
                          const gchar *reference);

Sets the reference that as used to create the .it8 reference

#### Parameters

it8 | a CdIt8 instance. |
reference | the instruemnt name, e.g. "colormunki" |

Since: 0.1.20

### cd_it8_set_enable_created ()

    void
    cd_it8_set_enable_created (CdIt8 *it8,
                               gboolean enable_created);

Sets if the 'CREATED' attribute should be written. This is mainly useful in the self test programs where we want to string compare the output data with a known reference.

#### Parameters

it8 | a CdIt8 instance. |
enable_created | Is 'CREATED' should be written |

Since: 0.1.33

### cd_it8_add_data ()

    void
    cd_it8_add_data (CdIt8 *it8,
                     const CdColorRGB *rgb,
                     const CdColorXYZ *xyz);

Adds a reading to this object. If either of `rgb` or `xyz` is NULL then a black reading (0.0, 0.0, 0.0) is added instead.

#### Parameters

it8 | a CdIt8 instance. |
rgb | a CdColorRGB, or `NULL` |
xyz | a CdColorXYZ, or `NULL` |

Since: 0.1.20

### cd_it8_add_option ()

    void
    cd_it8_add_option (CdIt8 *it8,
                       const gchar *option);

Sets any extra options that have to be set in the CCMX file

#### Parameters

it8 | a CdIt8 instance. |
option | A IT8 option, e.g. "TYPE_LCD" |

Since: 0.1.20

### cd_it8_set_matrix ()

    void
    cd_it8_set_matrix (CdIt8 *it8,
                       const CdMat3x3 *matrix);

Set the calibration matrix in the it8 file.

#### Parameters

it8 | a CdIt8 instance. |
matrix | a CdMat3x3. |

Since: 0.1.20

### cd_it8_set_spectrum_array ()

    void
    cd_it8_set_spectrum_array (CdIt8 *it8,
                               GPtrArray *data);

Set the spectral data

#### Parameters

it8 | a CdIt8 instance. |
data | the spectral data. | [transfer container][element-type CdSpectrum]

Since: 1.1.6

### cd_it8_add_spectrum ()

    void
    cd_it8_add_spectrum (CdIt8 *it8,
                         CdSpectrum *spectrum);

Adds a spectrum to the spectral array.

#### Parameters

it8 | a CdIt8 instance. |
spectrum | the spectral data |

Since: 1.1.6

### cd_it8_get_matrix ()

    const CdMat3x3 *
    cd_it8_get_matrix (CdIt8 *it8);

Gets the calibration matrix in the it8 file.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

a CdMat3x3.

Since: 0.1.20

### cd_it8_get_kind ()

    CdIt8Kind
    cd_it8_get_kind (CdIt8 *it8);

Gets the kind of IT8 file.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

a CdIt8Kind, e.g `CD_IT8_KIND_TI3`.

Since: 0.1.20

### cd_it8_get_normalized ()

    gboolean
    cd_it8_get_normalized (CdIt8 *it8);

Gets if the data should be written normlaised to y=100.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

`TRUE` if the data should be normalised.

Since: 0.1.20

### cd_it8_get_originator ()

    const gchar *
    cd_it8_get_originator (CdIt8 *it8);

Gets the file orginator.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

The originator, or `NULL` if unset

Since: 0.1.20

### cd_it8_get_title ()

    const gchar *
    cd_it8_get_title (CdIt8 *it8);

Gets the file title.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

The title, or `NULL` if unset

Since: 0.1.20

### cd_it8_get_spectral ()

    gboolean
    cd_it8_get_spectral (CdIt8 *it8);

Gets if the data is spectral or XYZ.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

`TRUE` if the data is in spectral bands.

Since: 0.1.20

### cd_it8_get_instrument ()

    const gchar *
    cd_it8_get_instrument (CdIt8 *it8);

Gets the instrument the file was created by.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

The instrument, or `NULL` if unset

Since: 0.1.20

### cd_it8_get_reference ()

    const gchar *
    cd_it8_get_reference (CdIt8 *it8);

Gets the reference the file was created against.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

The reference, or `NULL` if unset

Since: 0.1.20

### cd_it8_get_enable_created ()

    gboolean
    cd_it8_get_enable_created (CdIt8 *it8);

Gets if the 'CREATED' attribute will be written. This is typically only set in the self test programs.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

The reference, or `NULL` if unset

Since: 0.1.33

### cd_it8_get_data_size ()

    guint
    cd_it8_get_data_size (CdIt8 *it8);

Gets the data size.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

The number of RGB-XYZ readings in this object.

Since: 0.1.20

### cd_it8_get_data_item ()

    gboolean
    cd_it8_get_data_item (CdIt8 *it8,
                          guint idx,
                          CdColorRGB *rgb,
                          CdColorXYZ *xyz);

Gets a specific bit of data from this object. The returned data are absolute readings and are not normalised.

#### Parameters

it8 | a CdIt8 instance. |
idx | the item index |
rgb | the returned RGB value |
xyz | the returned XYZ value |

#### Returns

`TRUE` if the index existed.

Since: 0.1.20

### cd_it8_get_spectrum_array ()

    GPtrArray *
    cd_it8_get_spectrum_array (CdIt8 *it8);

Gets the spectral data of IT8 file.

#### Parameters

it8 | a CdIt8 instance. |

#### Returns

spectral data.

[transfer container][element-type CdSpectrum]

Since: 1.1.6

### cd_it8_get_spectrum_by_id ()

    CdSpectrum *
    cd_it8_get_spectrum_by_id (CdIt8 *it8,
                               const gchar *id);

Gets a specific spectrum in an IT8 file.

#### Parameters

it8 | a CdIt8 instance. |
id | the spectrum ID value |

#### Returns

spectrum, or `NULL`.

[transfer none]

Since: 1.1.6

### cd_it8_has_option ()

    gboolean
    cd_it8_has_option (CdIt8 *it8,
                       const gchar *option);

Finds an option in the file.

#### Parameters

it8 | a CdIt8 instance. |
option | a option, e.g. "TYPE_CRT" |

#### Returns

`TRUE` if the option is set

Since: 0.1.20

### cd_it8_get_xyz_for_rgb ()

    CdColorXYZ *
    cd_it8_get_xyz_for_rgb (CdIt8 *it8,
                            gdouble R,
                            gdouble G,
                            gdouble B,
                            gdouble delta);

Gets the XYZ value for a specific RGB value.

#### Parameters

it8 | a CdIt8 instance. |
R | the red value |
G | the green value |
B | the blue value |
delta | the smallest difference between colors, e.g. 0.01f |

#### Returns

A CdColorXYZ, or `NULL` if the sample does not exist.

[transfer none]

Since: 1.2.6

## Types and Values

### CD_IT8_ERROR

    #define CD_IT8_ERROR		(cd_it8_error_quark ())

### CD_IT8_TYPE_ERROR

    #define CD_IT8_TYPE_ERROR (cd_it8_error_get_type ())

### CD_TYPE_IT8

    #define CD_TYPE_IT8 (cd_it8_get_type ())

### struct CdIt8Class

    struct CdIt8Class {
    	GObjectClass		 parent_class;
    };

### enum CdIt8Error

Errors that can be thrown

#### Members

CD_IT8_ERROR_FAILED | the transaction failed for an unknown reason |
CD_IT8_ERROR_INVALID_FORMAT |  |
CD_IT8_ERROR_UNKNOWN_KIND |  |

### enum CdIt8Kind

The kind of IT8 file.

#### Members

CD_IT8_KIND_UNKNOWN |  |
CD_IT8_KIND_TI1 |  |
CD_IT8_KIND_TI3 |  |
CD_IT8_KIND_CCMX |  |
CD_IT8_KIND_CAL |  |
CD_IT8_KIND_CCSS |  |
CD_IT8_KIND_SPECT |  |
CD_IT8_KIND_CMF |  |

### CdIt8

    typedef struct _CdIt8 CdIt8;

## Property Details

### The `“instrument”` property

      “instrument”               gchar *

The instrument that created the results, e.g. "huey"

Flags: Read

Default value: NULL

Since: 0.1.20

### The `“kind”` property

      “kind”                     guint

The kind of IT8 file.

Flags: Read / Write

Default value: 0

Since: 0.1.20

### The `“normalized”` property

      “normalized”               gboolean

If the results file is normalized.

Flags: Read

Default value: FALSE

Since: 0.1.20

### The `“originator”` property

      “originator”               gchar *

The framework that created the results, e.g. "cd-self-test"

Flags: Read

Default value: NULL

Since: 0.1.20

### The `“reference”` property

      “reference”                gchar *

The reference that created the results, e.g. "colormunki"

Flags: Read

Default value: NULL

Since: 0.1.20

### The `“spectral”` property

      “spectral”                 gboolean

If the results file is spectral.

Flags: Read

Default value: FALSE

Since: 0.1.20

### The `“title”` property

      “title”                    gchar *

The file title, e.g. "Factor calibration".

Flags: Read

Default value: NULL

Since: 0.1.20