module Raster:sig
..end
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).
typescalar_type =
[ `Float16
| `Float32
| `Float64
| `Int16
| `Int32
| `Int64
| `Int8
| `UInt16
| `UInt32
| `UInt64
| `UInt8 ]
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
typebuffer =
[ `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 ]
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.typesample_semantics =
[ `Color of Gg.Color.profile * bool | `Other of string * int ]
`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
val rgba_l : sample_semantics
val gray_l : sample_semantics
val graya_l : sample_semantics
val pp_sample_semantics : Format.formatter -> sample_semantics -> unit
pp_sample_semantics ppf sem
prints a textual representation of sem
on ppf
.typesample_pack =
[ `FourCC of string * scalar_type option
| `Other of string * scalar_type option
| `PU8888 ]
`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
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
.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 typeval 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.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
.typet =
Gg.raster
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.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.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.(x,y,z)
starts is given by:
(Raster.first r) + z * z_pitch + y * y_pitch + x * x_pitch
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.