DiskHarmonicAnalysis#

class ktch.harmonic.DiskHarmonicAnalysis(n_harmonics=10, n_dim=3, registration='auto', scale=True, scale_method=None, align_parameter=True, reflect=False, return_transform=False, n_jobs=None, verbose=0)[source]#

Disk Harmonic Analysis

Parameters:

n_harmonicsint, default=10: Maximum radial degree ($n_\mathrm{max}$).
n_dimint, default=3: Dimension of the codomain, i.e. the number of components of the $\mathbb{R}^D$-valued function expanded on the unit disk. Any positive integer is supported; 2/3 are the common planar/surface mappings and 1 corresponds to a scalar field on the disk.
registration{“auto”, None, “first_order”, “moment”}, default=”auto”: Shape-registration method (2D/3D shape data only; requires n_dim in (2, 3)). "auto" (default) registers 2D/3D shape data with "first_order" and leaves other dimensions unregistered (None). None returns raw coefficients. "first_order" uses the first-order disk in-plane ellipse (the n=1, m=±1 modes) to align orientation, disk phase, and scale. "moment" aligns the codomain to the inertia-tensor principal axes and scales by centroid size.
scalebool, default=True: Whether registration removes size or keeps it. Only used when registration != None.
scale_method{None, “semi_major_axis”, “ellipse_area”, “centroid_size”},: default=None

Size measure when scale=True. None resolves to the method default: "ellipse_area" for "first_order" (all dimensions), "centroid_size" for "moment". "semi_major_axis" / "ellipse_area" require registration="first_order"; "centroid_size" requires registration="moment".
align_parameterbool, default=True: Parameter-domain (disk phase) alignment. "first_order" always applies it; align_parameter=False is not yet implemented and raises NotImplementedError.
reflectbool, default=False: Whether to also remove reflection (chirality). Honored by "moment". For "first_order" only reflect=False (orientation preserved) is implemented; reflect=True raises NotImplementedError.
return_transformbool, default=False: Append the registration parameters as extra output columns. Reserved for a future release (planned: the in-plane ellipse angle theta_0 and scale); setting True raises NotImplementedError.
n_jobsint, default=None: The number of jobs to run in parallel. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors.
verboseint, default=0: The verbosity level.

Notes

[Wolf_1979], [Verrall_Kakarala_1998], [Boyd_etal_2011], [Shaqfa_etal_2025]

The surface is expanded as:

\[\mathbf{p}(r, \theta) = \sum_{n=0}^{N} \sum_{m=-n}^{n} a_n^m\, \tilde{D}_n^m(r, \theta)\]

where $\tilde{D}_n^m$ are real-valued disk harmonic basis functions constructed from Bessel functions of the first kind $J_m$ and their derivative zeros $\lambda_{n,m}$:

\[\begin{split}\tilde{D}_n^0(r, \theta) &= N_{n,0}\, J_0(\lambda_{n,0}\, r) \\ \tilde{D}_n^m(r, \theta) &= \sqrt{2}\, N_{n,m}\, J_m(\lambda_{n,m}\, r)\, \cos(m\,\theta) \quad (m > 0) \\ \tilde{D}_n^m(r, \theta) &= \sqrt{2}\, N_{n,|m|}\, J_{|m|}(\lambda_{n,|m|}\, r)\, \sin(|m|\,\theta) \quad (m < 0)\end{split}\]

with normalization constants of Fourier–Bessel basis functions:

\[N_{n,m} = \frac{1}{\sqrt{\pi\,(1 - m^2/\lambda_{n,m}^2)\, J_m(\lambda_{n,m})^2}}\]

References

[Wolf_1979]

Wolf, K.B., 1979. Normal Mode Expansion and Bessel Series 221–251.

[Verrall_Kakarala_1998]

Verrall, S.C., Kakarala, R., 1998. Disk-harmonic coefficients for invariant pattern recognition. J. Opt. Soc. Am. A 15, 389.

[Boyd_etal_2011]

Boyd, J.P., Yu, F., 2011. Comparing seven spectral methods for interpolation and for solving the Poisson equation in a disk: Zernike polynomials, Logan–Shepp ridge polynomials, Chebyshev–Fourier Series, cylindrical Robert functions, Bessel–Fourier expansions, square-to-disk conformal mapping and radial basis functions. J. Comput. Phys. 230, 1408–1438.

[Shaqfa_etal_2025]

Shaqfa, M., Choi, G.P.T., Anciaux, G., Beyer, K., 2025. Disk harmonics for analysing curved and flat self-affine rough surfaces and the topological reconstruction of open surfaces. J. Comput. Phys. 522, 113578.

fit(X, y=None)[source]#

Fit the model (no-op for stateless transformer).

Parameters:

Xignored
yignored

Returns:

self

fit_transform(X, y=None, r_theta=None)[source]#

Fit and transform in a single step.

Overridden to support metadata routing of r_theta.

Parameters:

Xlist of array-like of shape (n_coords_i, n_dim): Coordinate values of n_samples.
yignored
r_thetalist of array-like of shape (n_coords_i, 2): Disk parameterization of n_samples.

Returns:

X_transformedndarray of shape (n_samples, n_features)

get_feature_names_out(input_features: None | npt.ArrayLike = None) → np.ndarray[source]#

Get output feature names.

Parameters:

input_featuresignored

Returns:

feature_names_outndarray of str objects: Transformed feature names.

get_metadata_routing()#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)#

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

inverse_transform(X_transformed, r_range=None, theta_range=None, n_max=None)[source]#

Reconstruct surfaces from disk harmonic coefficients.

Parameters:

X_transformedarray-like of shape (n_samples, n_features): Disk harmonic coefficients.
r_rangearray-like of shape (n_r,), optional: Radial coordinates. Defaults to np.linspace(0, 1, 100).
theta_rangearray-like of shape (n_theta,), optional: Angular coordinates. Defaults to np.linspace(0, 2*pi, 180).
n_maxint, optional: Maximum degree of harmonics to use. Defaults to self.n_harmonics.

Returns:

X_coordsndarray of shape (n_samples, n_theta, n_r, n_dim): Reconstructed surface coordinates.

Configure whether metadata should be requested to be passed to the inverse_transform method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to inverse_transform if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to inverse_transform.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

X_transformedstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for X_transformed parameter in inverse_transform.
n_maxstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for n_max parameter in inverse_transform.
r_rangestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for r_range parameter in inverse_transform.
theta_rangestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for theta_range parameter in inverse_transform.

Returns:

selfobject: The updated object.

set_output(*, transform=None)#

Set output container.

Refer to the user guide for more details and Introducing the set_output API for an example on how to use the API.

Parameters:

transform{“default”, “pandas”, “polars”}, default=None

Configure output of transform and fit_transform.

“default”: Default output format of a transformer
“pandas”: DataFrame output
“polars”: Polars output
None: Transform configuration is unchanged

Added in version 1.4: “polars” option was added.

Returns:

selfestimator instance: Estimator instance.

set_params(**params)#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

set_transform_request(*, r_theta: bool | None | str = '$UNCHANGED$') → DiskHarmonicAnalysis#

Configure whether metadata should be requested to be passed to the transform method.

The options for each parameter are:

True: metadata is requested, and passed to transform if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to transform.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

r_thetastr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for r_theta parameter in transform.

Returns:

selfobject: The updated object.

transform(X, r_theta=None)[source]#

Compute disk harmonic coefficients.

Parameters:

Xlist of array-like: Coordinate values of n_samples. The i-th element has shape (n_coords_i, n_dim) representing vertex coordinates.
r_thetalist of array-like of shape (n_coords_i, 2): Disk parameterization of n_samples. The i-th element holds (r, theta) polar coordinates.

Returns:

X_transformedndarray of shape (n_samples, n_features): Disk harmonic coefficients.