Struct EncoderOptions 

pub struct EncoderOptions { /* private fields */ }

Available on crate feature encoder only.

Integer option bag used to configure Draco encoding.

Options mirror the C++ Draco encoder style: global options apply to the whole geometry, while attribute options override a value for one attribute id and fall back to the global value when unset.

Common keys include quantization_bits (per-attribute precision), encoding_speed/decoding_speed, encoding_method, and prediction_scheme. Keys without an explicit setter are read and written with get_global_int / set_global_int.

Examples

use draco_core::EncoderOptions;

let mut options = EncoderOptions::new();
options.set_global_int("quantization_bits", 14); // default for all attributes
options.set_attribute_int(0, "quantization_bits", 10); // override attribute 0

assert_eq!(options.get_attribute_int(0, "quantization_bits", 0), 10);
// Attribute 1 has no override, so it falls back to the global value.
assert_eq!(options.get_attribute_int(1, "quantization_bits", 0), 14);

Implementations

impl EncoderOptions

pub fn new() -> Self

Creates options with Draco-compatible defaults.

pub fn get_encoding_speed(&self) -> i32

Returns the configured encoding speed, defaulting to 5.

pub fn get_decoding_speed(&self) -> i32

Returns the configured decoding speed target, defaulting to 5.

pub fn get_speed(&self) -> i32

Returns the maximum speed for both encoding/decoding. Matches C++ ExpertEncoder::GetSpeed() behavior.

pub fn set_compression_level(&mut self, level: i32)

Sets both speeds from a draco_encoder-style compression level.

The CLI’s -cl runs 0 (least compression) to 10 (most), the opposite sense of encoding_speed/decoding_speed, and converts with speed = 10 - compression_level before calling the same SetSpeedOptions this crate mirrors; this method does the same conversion and nothing else. level is not range-checked, matching the CLI, which passes an out-of-range -cl straight through the same subtraction rather than rejecting it.

pub fn get_compression_level(&self) -> i32

Returns 10 - get_speed(), the CLI’s compression level for the speed this instance currently carries.

A fresh EncoderOptions reports 5 here, not the CLI’s own default of 7 — the two tools default to different speeds (5 here, 3 there), and this getter reads what is actually set rather than what the CLI would have chosen.

pub fn set_attribute_quantization( &mut self, att_id: i32, quantization_bits: i32, )

Sets quantization_bits for one attribute id.

Equivalent to ExpertEncoder::SetAttributeQuantization and to what the CLI’s -qp/-qt/-qn/-qg resolve to once they have picked an attribute id for POSITION/TEX_COORD/NORMAL/GENERIC; this method takes the id directly rather than a geometry attribute type.

pub fn get_attribute_quantization(&self, att_id: i32) -> i32

Returns the quantization_bits set for one attribute id, or -1 if none was set for it or globally.

pub fn get_prediction_scheme(&self) -> i32

Returns the forced prediction scheme, or -1 for the encoder default.

pub fn set_prediction_scheme(&mut self, value: i32)

Forces a prediction scheme by numeric Draco method id.

pub fn prediction_search(&self) -> bool

Whether the encoder may choose a point-cloud attribute’s prediction scheme by estimating the cost of each candidate.

pub fn set_prediction_search(&mut self, enabled: bool)

Lets the encoder choose each attribute’s prediction scheme by the estimated cost of the candidates rather than by upstream’s fixed rule.

Off by default, and deliberately: the automatic choice is upstream’s, and this crate’s output is byte-identical to C++ Draco’s for the same input. Searching produces a different — smaller — stream, so it is a thing a caller asks for rather than a thing that happens to them.

What it buys, and why it exists at all: the automatic choice for a point-cloud attribute is always Difference, and differencing costs more than it saves whenever consecutive values do not correlate. Spherical-harmonic coefficients in a Gaussian splat are the case that prompted this — predicted they cost 6.35 bits per 8-bit value, coded directly 5.72, against an order-0 entropy of 5.685. The opposite case is just as real: on smoothly varying data, turning prediction off has made a file 2.5x larger. Neither is knowable from the attribute’s type, so this looks at its values.

It is worth turning on only for data of that shape, and the honest version of “that shape” is narrow. On a photogrammetry capture — eight million points carrying position and colour — the search finds nothing at all: both attributes are well served by differencing, and coding either directly is 27% worse. Attributes whose values do not follow their neighbours are what this is for, and a scanned surface is the opposite of that.

The cost is encode time and nothing else. The candidates are ranked by the same bit estimate the symbol coder uses to choose its own scheme, which is an entropy pass over each candidate’s symbols, not a second encode, and the winner’s estimate is what the coder is then handed rather than working it out again: on a splat of a million points and 58 attributes the option adds about a third to the encode. Decoding is unaffected, and every stream this can produce is one an ordinary decoder reads: the scheme is a byte the bitstream has always carried, PREDICTION_NONE included.

An attribute with an explicit prediction_scheme is left alone; a caller who named a scheme has already made this choice.

pub fn spatial_point_order(&self) -> bool

Whether a point cloud’s points may be reordered spatially before being encoded.

pub fn set_spatial_point_order(&mut self, enabled: bool)

Lets the encoder emit a point cloud’s points in a spatial order rather than in the order they were handed in.

Which spatial order is the encoder’s choice and not part of this option’s contract: today it is a Morton curve, and a later version may use a better curve, or spend more encode time on the order at slower encoding_speed settings. Every such stream decodes the same way; only the order of the decoded points and the size differ.

A point cloud’s point order carries no meaning: no connectivity refers to it, every attribute is read through the same point index, and a decoder reconstructs whatever order the stream has. So an encoder may choose it, and choosing it spatially is what makes the difference predictor predict from a neighbour instead of from whatever the exporter happened to write next.

This is the general one of the two. It was written for Gaussian splats, where it takes a scene from 53.02 bytes per point to 45.47, and it does more on ordinary captured geometry: a 223 MB photogrammetry point cloud of eight million coloured points goes from 6.26 bytes per point to 4.23, which is 32% and more than twice the splat’s share. Any cloud whose attributes vary through space rather than along its file order should expect something in that range.

The Morton curve is laid over a grid as fine as the positions’ own quantization_bits, up to 21 bits an axis. Both halves of that are measured: a coarser grid puts points the stream will distinguish into one cell, where their order is whatever the sort left them in, and a finer one sorts by differences the quantization discards.

Off by default for the same reason the prediction search is: the output differs, byte for byte, from what upstream C++ Draco writes for the same input, and this crate’s default is to match it.

This reorders the decoded points. Anything outside the file that indexes into it by point number — a sidecar array, an index written by another tool — will be pointing at different points afterwards. Nothing inside a .drc does, which is why this is expressible at all, but a caller who has such a thing is the one who knows.

It can also make a file bigger, and unlike the prediction search it does not check. The gain comes from attributes that vary through space; an attribute that varies along the order it was handed in — an index, a timestamp, anything written in sequence — is scrambled by the reorder and costs more afterwards. A cloud of positions plus a running integer tag grows by 14% here. It is not checked because the option is a statement about the order, not about the size: a caller who wants spatial locality in the decoded cloud wants it whether or not it also happens to compress better. Whoever wants only the smaller file can encode both ways and keep the smaller, which is what this would otherwise be doing on their behalf and at twice the encode time.

Applies to the sequential coder. The kd-tree coder chooses its own point order and this leaves it alone. A point cloud with no position attribute has nothing to sort by and is also left alone.

pub fn get_encoding_method(&self) -> Option<i32>

Returns the forced encoding method, if one was set.

pub fn set_encoding_method(&mut self, value: i32)

Forces an encoding method by numeric Draco method id.

pub fn set_version(&mut self, major: u8, minor: u8)

Sets the target Draco bitstream version.

pub fn get_version(&self) -> (u8, u8)

Returns the target Draco bitstream version, or (0, 0) for default.

pub fn set_global_int(&mut self, key: &str, value: i32)

Sets a global integer option.

pub fn get_global_int(&self, key: &str, default_val: i32) -> i32

Returns a global integer option or the supplied default.

pub fn set_attribute_int(&mut self, att_id: i32, key: &str, value: i32)

Sets an integer option for one attribute id.

pub fn get_attribute_int(&self, att_id: i32, key: &str, default_val: i32) -> i32

Returns an attribute integer option, falling back to the global value.

Trait Implementations

impl Clone for EncoderOptions

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EncoderOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for EncoderOptions

fn default() -> Self

Returns the “default value” for a type.