Package 'geozl'

Read the coefficients attached to a frame

Description

Only the frame header is read; the payload is not decompressed.

Usage

geozl_coeffs(frame)

Arguments

frame

A frame, as a raw vector.

Value

A list of integer vectors, or NULL when the frame carries none.

---

Compress a tile

Description

Compress a tile

Usage

geozl_compress(x, graph, coeffs = NULL)

Arguments

x	Tile samples, converted to the graph's datatype. Its geometry is not checked against the graph.
graph	A graph from geozl_graph().
coeffs	Optional list of integer vectors to attach to this frame. Read them back with geozl_coeffs(); geozl assigns them no meaning.

Value

The frame, as a raw vector.

---

Decompress a frame

Description

A frame does not record its datatype or shape; keep them beside it, as Rumi does.

Usage

geozl_decompress(
  frame,
  datatype = NULL,
  dim = NULL,
  as = NULL,
  nodata = NULL,
  verify = TRUE,
  max_output_size = NULL
)

Arguments

frame	A frame, as a raw vector.
datatype	The storage type the frame was written with. Without it the result is the raw native bytes.
dim	Optional dimensions for the result.
as	"double" (the default when datatype is given, as terra and stars hold rasters), "integer", or "raw" for the native bytes, which torch reads without a copy through torch_tensor_from_buffer().
nodata	Samples equal to this value become NA.
verify	Whether to check the frame's checksums.
max_output_size	Refuse frames that declare more output bytes than this; set it when reading untrusted frames.

Value

A vector of samples, with dim when given.

---

Build a reusable compression graph

Description

A graph fixes the recipe, the storage type and the predictor geometry for every tile compressed with it.

Usage

geozl_graph(
  x,
  method,
  width = NULL,
  planes = NULL,
  error = NULL,
  nodata = NULL,
  datatype = NULL
)

Arguments

x	Raster samples: a double, integer or raw vector or array. For a bounded-error graph it fixes the domain later tiles are checked against, so use data spanning the product.
method	A recipe such as "planar>zigzag>pfor" or "planar>zigzag>transpose>entropy"; see geozl_profile().
width, planes	Row width in samples and number of stacked images.
error	NULL or 0 for lossless, a positive number for an absolute bound (LINEAR), a percentage such as "1%" (LOG), or a full LINEAR, LOG or SQRT recipe.
nodata	A sentinel value marking missing samples. NA in x is stored as this value. NaN selects NaN handling, which float rasters with missing values get without asking.
datatype	Storage type: "uint16", terra's "INT2U" or GDAL's "UInt16", and so on for 8, 16, 32 and 64 bit integers and 16, 32 and 64 bit floats. Defaults to "int32" for integer, "float64" for double and "uint8" for raw input.

Details

The fastest-varying dimension of x is the row: width defaults to dim(x)[1] and planes to the last dimension of an array with three or more. An array shaped ⁠(x, y, band)⁠, as stars holds a raster, therefore produces the same frames as Python does for ⁠(band, y, x)⁠. The matrix from terra::values(r) is shaped ⁠(ncell, nlyr)⁠, so pass ⁠width = terra::ncol(r), planes = terra::nlyr(r)⁠. Row-based predictors reset at each plane; use ⁠width = nx * ny, planes = 1⁠ to predict across bands.

Samples are converted to datatype before compression. Integer types refuse values that are not whole or do not fit, and float types round to nearest. A raw vector is taken as native samples of datatype already.

Value

A geozl_graph. It wraps native state, so it is not thread-safe and does not survive saving and reloading.

Examples

tile <- matrix(1000L + 1:(64 * 64) %% 97L, 64, 64)
g <- geozl_graph(tile, "planar>zigzag>pfor", datatype = "uint16")
frame <- geozl_compress(tile, g)
back <- geozl_decompress(frame, "uint16", dim = dim(tile), as = "integer")
identical(back, tile)

---

Benchmark candidate recipes on a tile

Description

Compresses and decompresses x with every recipe the prior allows and ranks them by compression ratio. Recipes that do not apply to the input are left out.

Usage

geozl_profile(
  x,
  prior = "planar",
  width = NULL,
  planes = NULL,
  error = NULL,
  reps = 5L,
  nodata = NULL,
  datatype = NULL,
  verify = FALSE
)

Arguments

x	Raster samples: a double, integer or raw vector or array. For a bounded-error graph it fixes the domain later tiles are checked against, so use data spanning the product.
prior	One predictor plus the identity path: "planar", "med", "delta_w", "delta_n", "average", "wp_static" or "delta_1d". NULL tries every predictor and "none" only the no-predictor path.
width, planes	Row width in samples and number of stacked images.
error	NULL or 0 for lossless, a positive number for an absolute bound (LINEAR), a percentage such as "1%" (LOG), or a full LINEAR, LOG or SQRT recipe.
reps	Round trips per recipe; the best time is kept.
nodata	A sentinel value marking missing samples. NA in x is stored as this value. NaN selects NaN handling, which float rasters with missing values get without asking.
datatype	Storage type: "uint16", terra's "INT2U" or GDAL's "UInt16", and so on for 8, 16, 32 and 64 bit integers and 16, 32 and 64 bit floats. Defaults to "int32" for integer, "float64" for double and "uint8" for raw input.
verify	Whether to check checksums while timing decode. The frames carry checksums either way.

Value

A data frame with one row per recipe: graph, bytes, ratio, encode_mbps, decode_mbps and shannon_pct, the order-0 entropy bound as a percentage of the frame size.

---