cd-spectrum: colord Reference Manual

## cd-spectrum cd-spectrum — A single set of spectral values |

## Functions

CdSpectrum * | cd_spectrum_new ()
CdSpectrum * | cd_spectrum_sized_new ()
CdSpectrum * | cd_spectrum_planckian_new ()
CdSpectrum * | cd_spectrum_planckian_new_full ()
void | cd_spectrum_free ()
CdSpectrum * | cd_spectrum_dup ()
void | cd_spectrum_limit_min ()
void | cd_spectrum_limit_max ()
void | cd_spectrum_normalize ()
void | cd_spectrum_normalize_max ()
CdSpectrum * | cd_spectrum_subtract ()
gchar * | cd_spectrum_to_string ()
const gchar * | cd_spectrum_get_id ()
GArray * | cd_spectrum_get_data ()
gdouble | cd_spectrum_get_start ()
gdouble | cd_spectrum_get_end ()
gdouble | cd_spectrum_get_norm ()
gdouble | cd_spectrum_get_resolution ()
guint | cd_spectrum_get_size ()
gdouble | cd_spectrum_get_value_max ()
gdouble | cd_spectrum_get_value_min ()
gdouble | cd_spectrum_get_value ()
gdouble | cd_spectrum_get_value_raw ()
gdouble | cd_spectrum_get_wavelength ()
gdouble | cd_spectrum_get_value_for_nm ()
void | cd_spectrum_set_id ()
void | cd_spectrum_set_data ()
void | cd_spectrum_set_start ()
void | cd_spectrum_set_end ()
void | cd_spectrum_set_norm ()
void | cd_spectrum_set_value ()
void | cd_spectrum_add_value ()
void | cd_spectrum_set_wavelength_cal ()
void | cd_spectrum_get_wavelength_cal ()
CdSpectrum * | cd_spectrum_multiply ()
CdSpectrum * | cd_spectrum_multiply_scalar ()
CdSpectrum * | cd_spectrum_resample ()
CdSpectrum * | cd_spectrum_resample_to_size ()

## Description

Functions to manipulate spectral values.

## Functions

### cd_spectrum_new ()

    CdSpectrum *
    cd_spectrum_new (void);

Allocates a spectrum.

#### Returns

A newly allocated CdSpectrum object

Since: 1.1.6

### cd_spectrum_sized_new ()

    CdSpectrum *
    cd_spectrum_sized_new (guint reserved_size);

Allocates a spectrum with a preallocated size.

#### Parameters

reserved_size | the future size of the spectrum |

#### Returns

A newly allocated CdSpectrum object

Since: 1.1.6

### cd_spectrum_planckian_new ()

    CdSpectrum *
    cd_spectrum_planckian_new (gdouble temperature);

Allocates a Planckian spectrum at a specific temperature.

#### Parameters

temperature | the temperature in Kelvin |

#### Returns

A newly allocated CdSpectrum object

Since: 1.1.6

### cd_spectrum_planckian_new_full ()

    CdSpectrum *
    cd_spectrum_planckian_new_full (gdouble temperature,
                                    gdouble start,
                                    gdouble end,
                                    gdouble resolution);

Allocates a Planckian spectrum at a specific temperature.

#### Parameters

temperature | the temperature in Kelvin |
start | the new spectrum start |
end | the new spectrum end |
resolution | the resolution to use when resampling |

#### Returns

A newly allocated CdSpectrum object

Since: 1.3.1

### cd_spectrum_free ()

    void
    cd_spectrum_free (CdSpectrum *spectrum);

Deallocates a color spectrum.

#### Parameters

spectrum | the spectrum |

Since: 1.1.6

### cd_spectrum_dup ()

    CdSpectrum *
    cd_spectrum_dup (const CdSpectrum *spectrum);

#### Parameters

spectrum | a CdSpectrum instance. |

Since: 1.1.6

### cd_spectrum_limit_min ()

    void
    cd_spectrum_limit_min (CdSpectrum *spectrum,
                           gdouble value);

Ensures no values in the spectrum fall below a set limit. If they are found, set them to `value` .

#### Parameters

spectrum | a CdSpectrum instance |
value | the threshold value to limit the spectrum |

Since: 1.3.1

### cd_spectrum_limit_max ()

    void
    cd_spectrum_limit_max (CdSpectrum *spectrum,
                           gdouble value);

Ensures no values in the spectrum fall above a set limit. If they are found, set them to `value` .

#### Parameters

spectrum | a CdSpectrum instance |
value | the threshold value to limit the spectrum |

Since: 1.3.1

### cd_spectrum_normalize ()

    void
    cd_spectrum_normalize (CdSpectrum *spectrum,
                           gdouble wavelength,
                           gdouble value);

Normalizes a spectrum to a specific value at a specific wavelength.

#### Parameters

spectrum | a CdSpectrum instance |
wavelength | the wavelength in nm |
value | the value to normalize to |

Since: 1.1.6

### cd_spectrum_normalize_max ()

    void
    cd_spectrum_normalize_max (CdSpectrum *spectrum,
                               gdouble value);

Normalizes a spectrum to a specific value at its maximum value.

#### Parameters

spectrum | a CdSpectrum instance |
value | the value to normalize to |

Since: 1.2.6

### cd_spectrum_subtract ()

    CdSpectrum *
    cd_spectrum_subtract (CdSpectrum *s1,
                          CdSpectrum *s2,
                          gdouble resolution);

Subtracts one spectral plot from another. If the spectra have the same start, end and the same number of data points they are not resampled.

#### Parameters

s1 | a CdSpectrum instance, e.g. a sample |
s2 | a CdSpectrum instance, e.g. a dark calibration |
resolution | the resolution to use when resampling |

#### Returns

a CdSpectrum instance

Since: 1.3.1

### cd_spectrum_to_string ()

    gchar *
    cd_spectrum_to_string (CdSpectrum *spectrum,
                           guint max_width,
                           guint max_height);

Returns a graphical representation of the spectrum.

#### Parameters

spectrum | a CdSpectrum instance |
max_width | the terminal width |
max_height | the terminal height |

#### Returns

a printable ASCII string

Since: 1.3.1

### cd_spectrum_get_id ()

    const gchar *
    cd_spectrum_get_id (const CdSpectrum *spectrum);

Gets the spectral data.

#### Parameters

spectrum | a CdSpectrum instance. |

#### Returns

the textual ID of the sample

Since: 1.1.6

### cd_spectrum_get_data ()

    GArray *
    cd_spectrum_get_data (const CdSpectrum *spectrum);

Gets the spectral data. NOTE: This is not normalized

#### Parameters

spectrum | a CdSpectrum instance. |

#### Returns

spectral data.

[transfer none][element-type gdouble]

Since: 1.1.6

### cd_spectrum_get_start ()

    gdouble
    cd_spectrum_get_start (const CdSpectrum *spectrum);

Gets the start value of the spectral data.

#### Parameters

spectrum | a CdSpectrum instance. |

#### Returns

the value in nm

Since: 1.1.6

### cd_spectrum_get_end ()

    gdouble
    cd_spectrum_get_end (const CdSpectrum *spectrum);

Gets the end value of the spectral data.

#### Parameters

spectrum | a CdSpectrum instance. |

#### Returns

the value in nm

Since: 1.1.6

### cd_spectrum_get_norm ()

    gdouble
    cd_spectrum_get_norm (const CdSpectrum *spectrum);

Gets the normalization value of the spectral data. NOTE: This affects every value in the spectrum.

#### Parameters

spectrum | a CdSpectrum instance. |

#### Returns

the value

Since: 1.1.6

### cd_spectrum_get_resolution ()

    gdouble
    cd_spectrum_get_resolution (const CdSpectrum *spectrum);

Gets the divisor of the spectra, for instance a .

#### Parameters

spectrum | a CdSpectrum instance. |

#### Returns

the value

Since: 1.2.6

### cd_spectrum_get_size ()

    guint
    cd_spectrum_get_size (const CdSpectrum *spectrum);

Gets the size of the spectrum data.

#### Parameters

spectrum | a CdSpectrum instance. |

#### Returns

number of data items in this spectrum

Since: 1.1.6

### cd_spectrum_get_value_max ()

    gdouble
    cd_spectrum_get_value_max (const CdSpectrum *spectrum);

Gets the largest normalised value in the spectrum.

#### Parameters

spectrum | a CdSpectrum instance. |

Since: 1.3.1

### cd_spectrum_get_value_min ()

    gdouble
    cd_spectrum_get_value_min (const CdSpectrum *spectrum);

Gets the smallest normalised value in the spectrum.

#### Parameters

spectrum | a CdSpectrum instance. |

Since: 1.3.1

### cd_spectrum_get_value ()

    gdouble
    cd_spectrum_get_value (const CdSpectrum *spectrum,
                           guint idx);

Gets the spectrum data at a specified index.

#### Parameters

spectrum | a CdSpectrum instance. |
idx | an index into the data |

#### Returns

spectral data value, or -1 for invalid

Since: 1.1.6

### cd_spectrum_get_value_raw ()

    gdouble
    cd_spectrum_get_value_raw (const CdSpectrum *spectrum,
                               guint idx);

Gets the spectrum data at a specified index, without any normalization applied. Most people should use `cd_spectrum_get_value()` instead.

#### Parameters

spectrum | a CdSpectrum instance. |
idx | an index into the data |

#### Returns

spectral data value, or -1 for invalid

Since: 1.2.6

### cd_spectrum_get_wavelength ()

    gdouble
    cd_spectrum_get_wavelength (const CdSpectrum *spectrum,
                                guint idx);

Gets the wavelenth that corresponds to the specified index.

#### Parameters

spectrum | a CdSpectrum instance. |
idx | an index into the data |

#### Returns

wavelenth value in nm, or -1 for invalid

Since: 1.1.6

### cd_spectrum_get_value_for_nm ()

    gdouble
    cd_spectrum_get_value_for_nm (const CdSpectrum *spectrum,
                                  gdouble wavelength);

Gets the value from the spectral data for a given wavelength.

#### Parameters

spectrum | a CdSpectrum instance. |
wavelength | the wavelength in nm |

#### Returns

the value for the wavelength

Since: 1.1.6

### cd_spectrum_set_id ()

    void
    cd_spectrum_set_id (CdSpectrum *spectrum,
                        const gchar *id);

Sets a spectrum id.

#### Parameters

spectrum | the destination spectrum |
id | component id |

Since: 1.1.6

### cd_spectrum_set_data ()

    void
    cd_spectrum_set_data (CdSpectrum *spectrum,
                          GArray *value);

Sets the spectrum data.

#### Parameters

spectrum | the destination spectrum |
value | component value. | [element-type gdouble]

Since: 1.1.6

### cd_spectrum_set_start ()

    void
    cd_spectrum_set_start (CdSpectrum *spectrum,
                           gdouble start);

Set the start value of the spectal data in nm.

#### Parameters

spectrum | a CdSpectrum instance. |
start | the start value of the spectral data |

Since: 1.1.6

### cd_spectrum_set_end ()

    void
    cd_spectrum_set_end (CdSpectrum *spectrum,
                         gdouble end);

Set the end value of the spectal data in nm.

If there is already spectral data, the wavelength calibration will also be set automatically.

#### Parameters

spectrum | a CdSpectrum instance. |
end | the end value of the spectral data |

Since: 1.1.6

### cd_spectrum_set_norm ()

    void
    cd_spectrum_set_norm (CdSpectrum *spectrum,
                          gdouble norm);

Set the normalization value of the spectrum. NOTE: This affects every value in the spectrum.

#### Parameters

spectrum | a CdSpectrum instance. |
norm | the end value of the spectral data |

Since: 1.1.6

### cd_spectrum_set_value ()

    void
    cd_spectrum_set_value (CdSpectrum *spectrum,
                           guint idx,
                           gdouble data);

Overwrites the spectrum data at a specified index.

#### Parameters

spectrum | a CdSpectrum instance. |
idx | an index into the data |
data | a data value |

Since: 1.2.6

### cd_spectrum_add_value ()

    void
    cd_spectrum_add_value (CdSpectrum *spectrum,
                           gdouble data);

Adds a value in nm to the spectrum.

#### Parameters

spectrum | the spectrum |

Since: 1.1.6

### cd_spectrum_set_wavelength_cal ()

    void
    cd_spectrum_set_wavelength_cal (CdSpectrum *spectrum,
                                    gdouble c1,
                                    gdouble c2,
                                    gdouble c3);

Sets the calibration coefficients used to map pixel indexes to wavelengths.

This function will set the 'end' wavelength automatically, potentially overwriting the value set by `cd_spectrum_set_end()`.

#### Parameters

spectrum | a CdSpectrum instance |
c1 | the 1st coefficient |
c2 | the 2nd coefficient |
c3 | the 3rd coefficient |

Since: 1.3.1

### cd_spectrum_get_wavelength_cal ()

    void
    cd_spectrum_get_wavelength_cal (CdSpectrum *spectrum,
                                    gdouble *c1,
                                    gdouble *c2,
                                    gdouble *c3);

Gets the calibration coefficients used to map pixel indexes to wavelengths.

#### Parameters

spectrum | a CdSpectrum instance |
c1 | the 1st coefficient |
c2 | the 2nd coefficient |
c3 | the 3rd coefficient |

Since: 1.3.1

### cd_spectrum_multiply ()

    CdSpectrum *
    cd_spectrum_multiply (CdSpectrum *s1,
                          CdSpectrum *s2,
                          gdouble resolution);

Multiplies two spectra together.

#### Parameters

s1 | a CdSpectrum instance, possibly an illuminant. |
s2 | a CdSpectrum instance, possibly an absorption spectrum. |
resolution | the step size in nm |

#### Returns

a CdSpectrum instance

Since: 1.1.6

### cd_spectrum_multiply_scalar ()

    CdSpectrum *
    cd_spectrum_multiply_scalar (CdSpectrum *spectrum,
                                 gdouble value);

Multiplies a spectra with a scalar value.

#### Parameters

spectrum | a CdSpectrum instance |
value | a scalar value |

#### Returns

a CdSpectrum instance

Since: 1.3.5

### cd_spectrum_resample ()

    CdSpectrum *
    cd_spectrum_resample (CdSpectrum *spectrum,
                          gdouble start,
                          gdouble end,
                          gdouble resolution);

Resample a new spectrum with linear index to wavelength coefficients.

#### Parameters

spectrum | a CdSpectrum instance |
start | the new spectrum start |
end | the new spectrum end |
resolution | the resolution to use when resampling |

#### Returns

a CdSpectrum instance

Since: 1.3.1

### cd_spectrum_resample_to_size ()

    CdSpectrum *
    cd_spectrum_resample_to_size (CdSpectrum *spectrum,
                                  guint size);

Resample a new spectrum with the desired number of points.

#### Parameters

spectrum | a CdSpectrum instance |
size | the output spectrum size |

#### Returns

a CdSpectrum instance

Since: 1.3.4