Module Gg.Raster

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



Scalar types and buffers


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.

Sample semantics


type sample_semantics = [ `Color of Gg.Color.profile * bool | `Other of string * int ] 
The type for sample semantics.
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.

Sample format


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

Raster data


type t = Gg.raster 
The type for raster data.

Constructor, accessors


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

Functions


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

Predicates and comparisons


val equal : t -> t -> bool
equal r r' is r = r'.
val compare : t -> t -> int
compare r r' is Pervasives.compare r r'.

Printers


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.