## cd-it8 cd-it8 — Read and write IT8 color sample exchange files |

## Synopsis

    #define             CD_IT8_ERROR
    #define             CD_IT8_TYPE_ERROR
    enum                CdIt8Error;
    enum                CdIt8Kind;
    void                (*_cd_it8_reserved1)                (void);
    void                (*_cd_it8_reserved2)                (void);
    void                (*_cd_it8_reserved3)                (void);
    void                (*_cd_it8_reserved4)                (void);
    void                (*_cd_it8_reserved5)                (void);
    void                (*_cd_it8_reserved6)                (void);
    void                (*_cd_it8_reserved7)                (void);
    void                (*_cd_it8_reserved8)                (void);
    void                cd_it8_add_data                     (CdIt8 *it8,
                                                             const CdColorRGB *rgb,
                                                             const CdColorXYZ *xyz);
    void                cd_it8_add_option                   (CdIt8 *it8,
                                                             const gchar *option);
    GQuark              cd_it8_error_quark                  (void);
    gboolean            cd_it8_get_data_item                (CdIt8 *it8,
                                                             guint idx,
                                                             CdColorRGB *rgb,
                                                             CdColorXYZ *xyz);
    guint               cd_it8_get_data_size                (CdIt8 *it8);
    gboolean            cd_it8_get_enable_created           (CdIt8 *it8);
    const gchar *       cd_it8_get_instrument               (CdIt8 *it8);
    CdIt8Kind           cd_it8_get_kind                     (CdIt8 *it8);
    const CdMat3x3 *    cd_it8_get_matrix                   (CdIt8 *it8);
    gboolean            cd_it8_get_normalized               (CdIt8 *it8);
    const gchar *       cd_it8_get_originator               (CdIt8 *it8);
    const gchar *       cd_it8_get_reference                (CdIt8 *it8);
    gboolean            cd_it8_get_spectral                 (CdIt8 *it8);
    const gchar *       cd_it8_get_title                    (CdIt8 *it8);
    gboolean            cd_it8_has_option                   (CdIt8 *it8,
                                                             const gchar *option);
    gboolean            cd_it8_load_from_data               (CdIt8 *it8,
                                                             const gchar *data,
                                                             gsize size,
                                                             GError **error);
    gboolean            cd_it8_load_from_file               (CdIt8 *it8,
                                                             GFile *file,
                                                             GError **error);
    CdIt8 *             cd_it8_new                          (void);
    CdIt8 *             cd_it8_new_with_kind                (CdIt8Kind kind);
    gboolean            cd_it8_save_to_data                 (CdIt8 *it8,
                                                             gchar **data,
                                                             gsize *size,
                                                             GError **error);
    gboolean            cd_it8_save_to_file                 (CdIt8 *it8,
                                                             GFile *file,
                                                             GError **error);
    void                cd_it8_set_enable_created           (CdIt8 *it8,
                                                             gboolean enable_created);
    void                cd_it8_set_instrument               (CdIt8 *it8,
                                                             const gchar *instrument);
    void                cd_it8_set_kind                     (CdIt8 *it8,
                                                             CdIt8Kind kind);
    void                cd_it8_set_matrix                   (CdIt8 *it8,
                                                             const CdMat3x3 *matrix);
    void                cd_it8_set_normalized               (CdIt8 *it8,
                                                             gboolean normalized);
    void                cd_it8_set_originator               (CdIt8 *it8,
                                                             const gchar *originator);
    void                cd_it8_set_reference                (CdIt8 *it8,
                                                             const gchar *reference);
    void                cd_it8_set_spectral                 (CdIt8 *it8,
                                                             gboolean spectral);
    void                cd_it8_set_title                    (CdIt8 *it8,
                                                             const gchar *title);

## Description

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

## Details

### 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 ())

### enum CdIt8Error

    typedef enum {
    	CD_IT8_ERROR_FAILED,
    	CD_IT8_ERROR_LAST
    } CdIt8Error;

Errors that can be thrown

`CD_IT8_ERROR_FAILED` | the transaction failed for an unknown reason
`CD_IT8_ERROR_LAST` |

### enum CdIt8Kind

    typedef enum {
    	CD_IT8_KIND_UNKNOWN,
    	CD_IT8_KIND_TI1,
    	CD_IT8_KIND_TI3,
    	CD_IT8_KIND_CCMX,
    	CD_IT8_KIND_CAL,
    	CD_IT8_KIND_LAST
    } CdIt8Kind;

The kind of IT8 file.

### _cd_it8_reserved1 ()

    void                (*_cd_it8_reserved1)                (void);

### _cd_it8_reserved2 ()

    void                (*_cd_it8_reserved2)                (void);

### _cd_it8_reserved3 ()

    void                (*_cd_it8_reserved3)                (void);

### _cd_it8_reserved4 ()

    void                (*_cd_it8_reserved4)                (void);

### _cd_it8_reserved5 ()

    void                (*_cd_it8_reserved5)                (void);

### _cd_it8_reserved6 ()

    void                (*_cd_it8_reserved6)                (void);

### _cd_it8_reserved7 ()

    void                (*_cd_it8_reserved7)                (void);

### _cd_it8_reserved8 ()

    void                (*_cd_it8_reserved8)                (void);

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

`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

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

Since 0.1.20

### cd_it8_error_quark ()

    GQuark              cd_it8_error_quark                  (void);

Returns : | An error quark.

Since 0.1.0

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

`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_data_size ()

    guint               cd_it8_get_data_size                (CdIt8 *it8);

Gets the data size.

`it8` : | a CdIt8 instance.
Returns : | The number of RGB-XYZ readings in this object.

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.

`it8` : | a CdIt8 instance.
Returns : | The reference, or `NULL` if unset

Since 0.1.33

### cd_it8_get_instrument ()

    const gchar *       cd_it8_get_instrument               (CdIt8 *it8);

Gets the instrument the file was created by.

`it8` : | a CdIt8 instance.
Returns : | The instrument, or `NULL` if unset

Since 0.1.20

### cd_it8_get_kind ()

    CdIt8Kind           cd_it8_get_kind                     (CdIt8 *it8);

Gets the kind of IT8 file.

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

Since 0.1.20

### cd_it8_get_matrix ()

    const CdMat3x3 *    cd_it8_get_matrix                   (CdIt8 *it8);

Gets the calibration matrix in the it8 file.

`it8` : | a CdIt8 instance.
Returns : | a CdMat3x3.

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.

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

`it8` : | a CdIt8 instance.
Returns : | The originator, 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.

`it8` : | a CdIt8 instance.
Returns : | The reference, 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.

`it8` : | a CdIt8 instance.
Returns : | `TRUE` if the data is in spectral bands.

Since 0.1.20

### cd_it8_get_title ()

    const gchar *       cd_it8_get_title                    (CdIt8 *it8);

Gets the file title.

`it8` : | a CdIt8 instance.
Returns : | The title, or `NULL` if unset

Since 0.1.20

### cd_it8_has_option ()

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

Finds an option in the file.

`it8` : | a CdIt8 instance.
`option` : | a option, e.g. "TYPE_CRT"
Returns : | `TRUE` if the option is set

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.

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

`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_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.

`kind` : | a CdIt8Kind, e.g `CD_IT8_KIND_TI3`.
Returns : | a new CdIt8 object.

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.

`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_save_to_file ()

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

Saves a it8 file to disk

`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_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.

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

Since 0.1.33

### cd_it8_set_instrument ()

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

Sets the measuring instrument that created the .it8 file

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

Since 0.1.20

### cd_it8_set_kind ()

    void                cd_it8_set_kind                     (CdIt8 *it8,
                                                             CdIt8Kind kind);

Set the kind of IT8 file.

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

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.

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

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.

`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

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

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

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

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.

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

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.

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

Since 0.1.20