src.utils.ptransf.fps_decorator_transformer

Classes

FPSDecoratorTransformer(**kwargs)

class src.utils.ptransf.fps_decorator_transformer.FPSDecoratorTransformer(**kwargs)

Author:: Alberto M. Esmoris Pena

Class representing an FPS transformer that can be used to decorate different components of the framework.

A point cloud \(\pmb{P} = [\pmb{X} | \pmb{F} | \pmb{y}]\) can be reduced to an FPS representation \(\pmb{P'} = [\pmb{X'} | \pmb{F'} | \pmb{y'}]\). More concretely, an input point cloud with dimensionalities \(\pmb{X} \in \mathbb{R}^{m \times n_x}\), \(\pmb{F} \in \mathbb{R}^{m \times n_f}\), \(\pmb{y} \in \mathbb{Z}^{m}\) will be transformed to a representation with dimensionalities \(\pmb{X'} \in \mathbb{R}^{R \times n_x}\), \(\pmb{F'} \in \mathbb{R}^{R \times n_f}\), \(\pmb{y'} \in \mathbb{Z}^{R}\) where \(R \leq m\).

Variables:

num_points (int or str) – The number of points \(R\) the input points must be reduced to. In other words, for a given number of input points \(m_1\), the reduced number of points will be \(R\). For another, let us say different (i.e., \(m_1 \neq m_2\)) number of points, the reduced number of points will also be \(R\). Alternatively, it can be given as a string. If so, it is understood as an expression that can be evaluated, where “m” is the number of input points. For instance: “m/2” means the FPS will consider half of the input points.
fast (bool) – A flag to enable the fast-computation mode. When True, a random uniform subsampling will be computed before the furthest point sampling so the latest is faster because it is not considering the entire input point cloud.
threads – See PointCloudSamplerDecorator.
num_encoding_neighbors – See PointCloudSamplerDecorator.
num_decoding_neighbors – See PointCloudSamplerDecorator.
release_encoding_neighborhoods – See PointCloudSamplerDecorator.
representation_report_path – See RepresentationReportPath

__init__(**kwargs)

Initialize/instantiate a furthest point sampling decorator object.

Parameters:

kwargs – The key-word specification to instantiate the FPSDecoratorTransformer.

Keyword Arguments:

num_points (int or str) – The number of points \(R\) the input points must be reduced to. In other words, for a given number of input points \(m_1\), the reduced number of points will be \(R\). For another, let us say different (i.e., \(m_1 \neq m_2\)) number of points, the reduced number of points will also be \(R\). Alternatively, it can be given as a string. If so, it is understood as an expression that can be evaluated, where “m” is the number of input points. For instance: “m/2” means the FPS will consider half of the input points.
num_encoding_neighbors (int) –
See PointCloudSamplerDecorator.__init__().
num_decoding_neighbors (int) –
See PointCloudSamplerDecorator.__init__().
release_encoding_neighborhoods (bool) –
See PointCloudSamplerDecorator.__init__().
fast (bool) –
A flag to enable the fast-computation mode. When True, a random uniform subsampling will be computed before the furthest point sampling so the latest is faster because it is not considering the entire input point cloud.
threads (int) –
See PointCloudSamplerDecorator.__init__().
representation_report_path (str) –
See PointCloudSamplerDecorator.__init__().

transform(X, F=None, y=None, out_prefix=None): See PointCloudSamplerDecorator.transform().

eval_num_points(X=None, m=None)

Evaluate the number of points if it is a string and return the result, otherwise return the number directly.

Parameters:

X (np.ndarray or None) – The structure space matrix representing the point cloud (rows are columns),
m (int or None) – The number of points (when not given, the number of rows in X will be considered to initialize m) in the point cloud.

Returns:

The number of points that must be obtained after applying the transformation.

Return type:

int

static resolve_num_points(num_points, m)

Resolve a num_points specification to an integer count.

Accepts an integer (returned as-is) or a string expression evaluated with m bound to the size of the input cloud (e.g. "m/2"). Lifted from eval_num_points() so callers outside this class (notably the TORF C++ binding dispatch) can reuse the same resolution logic without instantiating FPSDecoratorTransformer.

Parameters:

num_points (int or str) – The number of points (int) or expression (str).
m (int) – The size of the input cloud, used when num_points is a string expression.

Returns:

Resolved integer target count (at least 1).

Return type:

int

static resolve_fast_to_mode(fast)

Map a Python fast flag to the numeric mode integer used by the C++ FurthestPointSubsampler via the TORF binding.

False -> 0 (exact 3D FPS; FurthestPointSubsampler.sample3D()).
True -> 2 (random sample; FurthestPointSubsampler.randomSample3D()). Semantic match to the existing Python decorator’s np.random.shuffle path; not bit-identical because the RNG is C++.
int in 0..4 -> forwarded as-is.

This is the single source of truth for the bool-to-mode mapping consumed by the C++ TORF binding. The existing Python transform() method does not call this helper because it dispatches to Open3D and NumPy paths that are not bit-identical to the C++ FurthestPointSubsampler modes; rewiring it through this method would silently alter Python-decorator results.

Changing the default for True is a one-line edit here.

Parameters:: fast – Bool or int 0..4. Numpy scalars (np.bool_, np.int64 etc.) are coerced via .item() before the type check so configs loaded through pandas / non-JSON pipelines do not hit a spurious ValueError.
Returns:: Mode integer in 0..4.
Return type:: int
Raises:: ValueError – when fast is not a bool nor an int in 0..4.