Raw data: Gwyddion Library Reference Manual

## Raw data Raw data — Raw data conversion |

## Functions

void | gwy_convert_raw_data ()
guint | gwy_raw_data_size ()
guint | gwy_raw_data_size_bits ()
void | gwy_memcpy_byte_swap ()

## Types and Values

enum | GwyRawDataType
enum | GwyByteOrder

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

## Functions

### gwy_convert_raw_data()

    void
    gwy_convert_raw_data (gconstpointer data,
                          gsize nitems,
                          gssize stride,
                          GwyRawDataType datatype,
                          GwyByteOrder byteorder,
                          gdouble *target,
                          gdouble scale,
                          gdouble offset);

Converts a block of raw data items to doubles.

Note that conversion from 64bit integral types may lose information as they have more bits than the mantissa of doubles. All other conversions should be exact.

For backward reading, pass -1 (or other negative value) as `stride` and point `data` to the last raw item instead of the first. More precisely, `data` must point to the first byte of the last raw value, not to the very last byte (for most data sizes this is intuitive, but 12bit data may involve some head scracthing). Zero `stride` is also allowed and results in `target` being filled with a constant value.

If the raw data size is not a whole number of bytes, parameter `byteorder` gives the order in which the pieces are packed into bytes. However, the usual order is to start from the high bits regardless of the machine endianness, so you normally always pass `GWY_BYTE_ORDER_BIG_ENDIAN` for fractional sized data.

For 12bit data only the big endian variant is defined at present. It means always storing the highest remaining bits of the 12bit value to the highest available bits of the byte, as TIFF and various cameras normally do.

For fractional sized data parameter `stride` specifies both the stride (always measured in raw values) and starting position within the first byte:

- For 1bit data `stride` is equal to 8`S` + `R`, where `S` is the actual stride. `R` = 0 means start conversion from the first bit and `R` = 1 from the second bit, …, up to `R` = 7 meaning starting from the last bit (which one is first depends on `byteorder`).
- For 4bit data `stride` is equal to 2`S` + `R`, where `S` is the actual stride. `R` = 0 means start conversion from the first nibble and `R` = 1 from the second nibble (which one is first depends on `byteorder`).
- For 12bit data `stride` is equal to 2`S` + `R`, where `S` is the actual stride. `R` = 0 means the conversion starts from a value split 8+4 (in forward direction), whereas `R` = 1 means the conversion starts from the value split 4+8.
- `R` is always positive and its meaning does not change for negative `S`.

For example, consider conversion of 3 nibbles of 4bit data (in the usual big endian order). This is how they will be read to the output:

- [0 1] [2 .] [. .] for `R` = 0, `S` = 1 (`stride` = 2), starting from the first byte.
- [. 0] [1 2] [. .] for `R` = 1, `S` = 1 (`stride` = 3), starting from the first byte.
- [0 .] [1 .] [2 .] for `R` = 0, `S` = 2 (`stride` = 4), starting from the first byte.
- [. .] [. 2] [1 0] for `R` = 1, `S` = -1 (`stride` = -1), starting from the last byte.
- [. .] [2 1] [0 .] for `R` = 0, `S` = -1 (`stride` = -2), starting from the last byte.

#### Parameters

data | Pointer to the input raw data to be converted to doubles. The data type is given by `datatype` and `byteorder` . |
nitems | Data block length, i.e. the number of consecutive items to convert. |
stride | For whole-byte sized data, item stride in the raw data, measured in raw values. For fractional sizes the interpretation is more complicated, see the description body. Usually pass 1 (contiguous, non-fractional sized data). |
datatype | Type of the raw data items. |
byteorder | Byte order of the raw data. The byte order must be explicit, i.e. `GWY_BYTE_ORDER_IMPLICIT` is not valid. For sub-byte sized data `byteorder` instead gives the order of values within one byte. |
target | Array of `nitems` to store the converted input data to. |
scale | Factor to multiply the data with. |
offset | Constant to add to the data after multiplying with `scale` . |

### gwy_raw_data_size()

    guint
    gwy_raw_data_size (GwyRawDataType datatype);

Reports the size of a single raw data item in bytes.

For raw data types which are not whole bytes (whether smaller or larger, like 12bit), zero is returned. Use `gwy_raw_data_size_bits()` to get the size in bits.

#### Parameters

datatype | Raw data type. |

#### Returns

The size (in bytes) of a single raw data item of type `datatype` .

### gwy_raw_data_size_bits()

    guint
    gwy_raw_data_size_bits (GwyRawDataType datatype);

Reports the size of a single raw data item in bits.

If the data type is known to be whole bytes, `gwy_raw_data_size()` is usually simpler to use.

#### Parameters

datatype | Raw data type. |

#### Returns

The size (in bits) of a single raw data item of type `datatype` .

### gwy_memcpy_byte_swap()

    void
    gwy_memcpy_byte_swap (const guint8 *source,
                          guint8 *dest,
                          gsize item_size,
                          gsize nitems,
                          gsize byteswap);

Copies a block of memory swapping bytes along the way.

The bits in `byteswap` correspond to groups of bytes to swap: if j-th bit is set, adjacent groups of 2j bits are swapped. For example, value 3 means items will be divided into couples (bit 1) of bytes and adjacent couples of bytes swapped, and then divided into single bytes (bit 0) and adjacent bytes swapped. The net effect is reversal of byte order in groups of four bytes. More generally, if you want to reverse byte order in groups of size 2j, use byte swap pattern j-1.

When `byteswap` is zero, this function reduces to plain `memcpy()`.

#### Parameters

source | Source memory block. |
dest | Destination memory location. |
item_size | Size of one copied item, it should be a power of two. |
nitems | Number of items of size `item_size` to copy. |
byteswap | Byte swap pattern. |

## Types and Values

### enum GwyRawDataType

Types of raw data.

They are used with `gwy_convert_raw_data()`. Multibyte types usually need to be complemented with GwyByteOrder to get a full type specification.

#### Members

GWY_RAW_DATA_SINT8 | Signed 8bit integer (one byte). |
GWY_RAW_DATA_UINT8 | Unsigned 8bit integer (one byte). |
GWY_RAW_DATA_SINT16 | Signed 16bit integer (two bytes). |
GWY_RAW_DATA_UINT16 | Unsigned 16bit integer (two bytes). |
GWY_RAW_DATA_SINT32 | Signed 32bit integer (four bytes). |
GWY_RAW_DATA_UINT32 | Unsigned 32bit integer (four bytes). |
GWY_RAW_DATA_SINT64 | Signed 64bit integer (eight bytes). |
GWY_RAW_DATA_UINT64 | Unsigned 64bit integer (eight bytes). |
GWY_RAW_DATA_HALF | Half-precision floating point number (two bytes). |
GWY_RAW_DATA_FLOAT | Single-precision floating point number (four bytes). |
GWY_RAW_DATA_REAL | Pascal ‘real’ floating point number (six bytes). |
GWY_RAW_DATA_DOUBLE | Double-precision floating point number (eight bytes). |
GWY_RAW_DATA_BIT | Unsigned 1bit integer (one bit). |
GWY_RAW_DATA_SINT4 | Signed 4bit integer (one nibble). |
GWY_RAW_DATA_UINT4 | Unsigned 4bit integer (one nibble). |
GWY_RAW_DATA_SINT12 | Signed 12bit integer (byte and half). |
GWY_RAW_DATA_UINT12 | Unsigned 12bit integer (byte and half). |
GWY_RAW_DATA_SINT24 | Signed 24bit integer (three bytes). |
GWY_RAW_DATA_UINT24 | Unsigned 24bit integer (three bytes). |
GWY_RAW_DATA_EXTENDED | x86 ‘extended’ floating point number (ten bytes). The values are assumed closely packed, which should be the case for old files, even though they would be usually aligned to 4 or 8 byte boundaries nowadays. |

### enum GwyByteOrder

Type of byte order.

Note all types are valid for all functions.

#### Members

GWY_BYTE_ORDER_NATIVE | Native byte order for the system the code is running on. |
GWY_BYTE_ORDER_LITTLE_ENDIAN | Little endian byte order (the same as `G_LITTLE_ENDIAN`). |
GWY_BYTE_ORDER_BIG_ENDIAN | Big endian byte order (the same as `G_BIG_ENDIAN`). |
GWY_BYTE_ORDER_IMPLICIT | Byte order implied by data, for instance a byte-order-mark (Since 2.60). |