Utility helpers

Utility functions for Gaussian Splatting operations.

gsply.utils.sh2rgb(sh)

Convert SH DC coefficients to RGB colors.

Parameters:

sh (ndarray | float) – SH DC coefficients (N, 3) or scalar

Return type:

ndarray | float

Returns:

RGB colors in [0, 1] range

Example

>>> import gsply
>>> sh = np.array([[0.0, 0.5, -0.5]])
>>> rgb = gsply.sh2rgb(sh)
>>> print(rgb)  # [[0.5, 0.641, 0.359]]

gsply.utils.rgb2sh(rgb)

Convert RGB colors to SH DC coefficients.

Parameters:

rgb (ndarray | float) – RGB colors in [0, 1] range (N, 3) or scalar

Return type:

ndarray | float

Returns:

SH DC coefficients

Example

>>> import gsply
>>> rgb = np.array([[1.0, 0.5, 0.0]])
>>> sh = gsply.rgb2sh(rgb)

gsply.utils.sigmoid(x)

Compute sigmoid function (inverse logit) with numerical stability.

Optimized for both scalar and array inputs using Numba. Formula: 1 / (1 + exp(-x))

Parameters:

x (ndarray | float) – Input values (logits)

Return type:

ndarray | float

Returns:

Values in [0, 1] range (probabilities)

gsply.utils.logit(x, eps=1e-06)

Compute logit function (inverse sigmoid) with numerical stability.

Optimized for both scalar and array inputs using Numba. Formula: log(x / (1 - x))

Parameters:

• x (ndarray | float) – Input values in [0, 1] range (probabilities)

• eps (float) – Epsilon for numerical stability (clamping)

Return type:

ndarray | float

Returns:

Logit values

gsply.utils.apply_pre_activations(data, *, min_scale=9.999999747378752e-05, max_scale=100.0, min_quat_norm=9.99999993922529e-09, inplace=True)

Activate GSData attributes (scales, opacities, quaternions) in a single fused pass.

This function uses a fused Numba kernel that processes all three attributes together for optimal performance (~8-15x faster than individual operations).

Parameters:

• data (GSData) – GSData instance to process

• min_scale (float) – Minimum allowed scale value after exponentiation

• max_scale (float) – Maximum allowed scale value after exponentiation

• min_quat_norm (float) – Norm floor for normalizing quaternions (avoids NaNs)

• inplace (bool) – If False, returns a copy before activation

Return type:

GSData

Returns:

GSData with activated attributes (either modified in-place or copy)

Example

>>> import gsply
>>> data = gsply.plyread("scene_logits.ply")
>>> gsply.apply_pre_activations(data, inplace=True)

gsply.utils.apply_pre_deactivations(data, *, min_scale=1e-09, min_opacity=0.0001, max_opacity=0.9999, inplace=True)

Deactivate GSData attributes (scales, opacities) in a single fused pass.

This function uses a fused Numba kernel that processes scales and opacities together for optimal performance (~8-15x faster than individual operations).

Parameters:

• data (GSData) – GSData instance to process

• min_scale (float) – Minimum allowed scale value before logarithm

• min_opacity (float) – Minimum allowed opacity value before logit

• max_opacity (float) – Maximum allowed opacity value before logit

• inplace (bool) – If False, returns a copy before deactivation

Return type:

GSData

Returns:

GSData with deactivated attributes (either modified in-place or copy)

Example

>>> import gsply
>>> data = gsply.GSData(...)  # Linear format
>>> gsply.apply_pre_deactivations(data, inplace=True)