module Raster: sig .. end

Raster data.

WARNING. This interface is subject to change in the future.

Raster data organizes data samples of any dimension in discrete 1D, 2D (images) or 3D space.

A sample has a semantics that defines its dimension and the meaning of its components. For example a 4D sample could represent a linear sRGBA sample. Samples are stored in a linear buffer of scalars of a given type. A sample can use one scalar per component, can be packed in a single scalar or may have no direct obvious relationship to buffer scalars (compressed data). A sample format defines the semantics and scalar storage of a sample.

A raster data value is a collection of samples indexed by width, height and depth (i.e. x, y, z) stored in a buffer. It defines the sample data, the extents of the index and the sample format.

Spatial convention. If the sample index has to be interpreted spatially. It must be interpreted relative to the origin of a right-handed coordinate system. This means that the first sample, indexed by (0, 0, 0) is the bottom-left backmost sample (bottom-left sample for an image).

type scalar_type = [ `Float16
       | `Float32
       | `Float64
       | `Int16
       | `Int32
       | `Int64
       | `Int8
       | `UInt16
       | `UInt32
       | `UInt64
       | `UInt8 ] 

The type for scalar types.

val scalar_type_byte_count : scalar_type -> int

scalar_type_byte_count st is the number of bytes used by a scalar of type st.

val pp_scalar_type : Format.formatter -> scalar_type -> unit

pp_scalar_type ppf st prints a textual representation of st on ppf.

type ('a, 'b) b_array = ('a, 'b, Bigarray.c_layout) Bigarray.Array1.t 

The type for big arrays.

type buffer = [ `A_Float64 of float array
       | `B_Float16 of (int, Bigarray.int16_unsigned_elt) b_array
       | `B_Float32 of (float, Bigarray.float32_elt) b_array
       | `B_Float64 of (float, Bigarray.float64_elt) b_array
       | `B_Int16 of (int, Bigarray.int16_signed_elt) b_array
       | `B_Int32 of (int32, Bigarray.int32_elt) b_array
       | `B_Int64 of (int64, Bigarray.int64_elt) b_array
       | `B_Int8 of (int, Bigarray.int8_signed_elt) b_array
       | `B_UInt16 of (int, Bigarray.int16_unsigned_elt) b_array
       | `B_UInt32 of (int32, Bigarray.int32_elt) b_array
       | `B_UInt64 of (int64, Bigarray.int64_elt) b_array
       | `B_UInt8 of (int, Bigarray.int8_unsigned_elt) b_array
       | `S_UInt8 of string ] 

The type for linear buffer of scalars.

val buffer_scalar_type : buffer -> scalar_type

buffer_scalar_type b is b's buffer scalar type.

val pp_buffer : Format.formatter -> buffer -> unit

pp_buffer b prints a textual representation of b on ppf. Does not print the buffer's data.

type sample_semantics = [ `Color of Gg.Color.profile * bool | `Other of string * int ] 

The type for sample semantics.

• `Color (p, alpha) is for color samples from the color profile p. alpha indicates if there's an alpha component on the right of the color components.
• `Other(label, dim) is for samples of dim dimension identified by label.

val rgb_l : sample_semantics

rgb_l is for linear RGB samples from the Gg.Color.p_rgb_l profile.

val rgba_l : sample_semantics

rgba_l is for linear RGB samples from the Gg.Color.p_rgb_l profile with an alpha component.

val gray_l : sample_semantics

gray_l is for linear Gray samples from the Gg.Color.p_gray_l profile.

val graya_l : sample_semantics

graya_l is for linear Gray samples from the Gg.Color.p_gray_l luminance with an alpha component.

val pp_sample_semantics : Format.formatter -> sample_semantics -> unit

pp_sample_semantics ppf sem prints a textual representation of sem on ppf.

type sample_pack = [ `FourCC of string * scalar_type option
       | `Other of string * scalar_type option
       | `PU8888 ] 

The type for sample packs. A sample pack describes storage for samples that do not use one scalar per component.

• `PU8888. An arbitrary 4D sample X, Y, Z, W with unsigned 8 bits components packed in a single `Uint32 scalar as 0xXXYYZZWWl.
• `FourCC(code, restrict). A sample is stored according to the format specified by the FourCC code, a string of length 4. If restrict is specified the pack can only be used with the corresponding scalar type. For example `FourCC("DXT5", Some `Uint64) can be used to specify a buffer of DXT5 compressed data. `FourCC can also be used to describe the numerous YUV packed pixel formats.
• `Other(label, restrict). A sample is stored in some other packing scheme identified by label, restrict has the same meaning as in `FourCC.

val pp_sample_pack : Format.formatter -> sample_pack -> unit

pp_sample_pack ppf pack prints a textual representation of pack on ppf.

type sample_format 

The type for sample formats.

val sample_format_v : ?pack:sample_pack ->
       sample_semantics ->
       scalar_type -> sample_format

sample_format_v pack sem st is a sample format with semantics sem and scalar type st. If pack is absent one scalar of type st per sample component is used. If present, see Gg.Raster.sample_pack.
Raises Invalid_argument if pack is incompatible with st, see Gg.Raster.sample_pack or if a pack `FourCC code is not made of 4 bytes.

val sf_semantics : sample_format -> sample_semantics

sf_semantics sf is sf's semantics.

val sf_scalar_type : sample_format -> scalar_type

sf_scalar_type sf is sf's buffer scalar type

val sf_pack : sample_format -> sample_pack option

sf_pack sf is sf's sample pack, if any.

val sf_dim : sample_format -> int

sf_dim sf is sf's sample dimension.

val sf_scalar_count : ?first:int ->
       ?w_skip:int ->
       ?h_skip:int -> w:int -> ?h:int -> ?d:int -> sample_format -> int

sf_scalar_count first w_skip h_skip w h d sf is the minimal number of scalars needed to hold a raster data with the corresponding parameters, see Gg.Raster.v for their description.
Raises Invalid_argument if sf is packed.

val pp_sample_format : Format.formatter -> sample_format -> unit

pp_sample_format ppf sf prints a textual representation of sf on ppf.

type t = Gg.raster 

The type for raster data.

val v : ?res:Gg.v3 ->
       ?first:int ->
       ?w_skip:int ->
       ?h_skip:int ->
       w:int ->
       ?h:int ->
       ?d:int -> sample_format -> buffer -> t

v res first w_skip h_skip w h d sf buf is raster data with sample format sf and buffer b.

• w, h, d, specify the index width, height and depth, in number of samples. h and d default to 1.
• first, buffer scalar index where the data of the first sample is stored.
• w_skip, number of buffer scalars to skip between two consecutive lines, defaults to 0.
• h_skip, number of buffer scalars to skip between two consecutive planes, defaults to 0.
• res, is an optional sample resolution specification in samples per meters.

For certain sample formats first, w_skip and h_skip can be used to specify subspaces in the collection of samples, see Gg.Raster.sub.

The function Gg.Raster.pitches can be used to easily compute the buffer scalar index where a sample (x,y,z) starts.
Raises Invalid_argument if w, h or d is not positive or if first, w_skip or h_skip is negative. Or if the scalar type of sf doesn't match (Raster.buffer_scalar_type b).

val res : t -> Gg.v3 option

res r is r's resolution in sample per meters, if any.

val first : t -> int

first r is the buffer scalar index where the first sample is stored.

val w_skip : t -> int

w_skip r is the number of buffer scalars to skip between two consecutive lines.

val h_skip : t -> int

f_h_skip r is the number of buffer scalars to skip between two consecutive planes.

val w : t -> int

w r is the index width in number of samples.

val h : t -> int

h r is the index height in number of samples.

val d : t -> int

d r is the index depth in number of samples.

val sample_format : t -> sample_format

f_sample_format r is r's sample format.

val buffer : t -> buffer

buffer r is r's format.

val dim : t -> int

dim r is r's index dimension from 1 to 3.

val size2 : t -> Gg.size2

size2 r is r's index width and height as floats.

val size3 : t -> Gg.size3

size3 r is r's index width, height and depth as floats.

val sub : ?x:int ->
       ?y:int -> ?z:int -> ?w:int -> ?h:int -> ?d:int -> t -> t

sub x y z w h d r is a raster corresponding to a subset of the index of r. Both r and the resulting raster share the same buffer.

• x, y, z, new sample origin of the raster data, defaults to (0, 0, 0).
• w, h, d, new size of the index, defaults to r's sizes minus the new sample origin.

Raises Invalid_argument, if the sample format of r is packed, if the origin is out of bounds or if new size is larger than r's size.

val pitches : t -> int * int * int

pitches r is (x_pitch, y_pitch, z_pitch) where

• x_pitch is the number of buffer scalars from sample to sample.
• y_pitch is the number of buffer scalars from line to line.
• z_pitch is the number of buffer scalars from plane to plane.

The buffer index where the sample (x,y,z) starts is given by:

(Raster.first r) + z * z_pitch + y * y_pitch + x * x_pitch

Raises Invalid_argument if the sample format of r is packed.

val equal : t -> t -> bool

equal r r' is r = r'.

val compare : t -> t -> int

compare r r' is Pervasives.compare r r'.

val to_string : t -> string

to_string r is a textual representation of r. Doesn't print the buffer samples.

val pp : Format.formatter -> t -> unit

pp ppf t prints a textual represenation of t on ppf. Doesn't print the buffer samples.