optionstratlib_math/surfaces/traits.rs
1/******************************************************************************
2 Author: Joaquín Béjar García
3 Email: jb@taunais.com
4 Date: 23/2/25
5******************************************************************************/
6use crate::error::SurfaceError;
7use crate::surfaces::Surface;
8
9/// A trait for objects that can generate a mathematical surface in 3D space.
10///
11/// This trait defines a single method, [`Surfacable::surface`], which is responsible for
12/// calculating or constructing a [`Surface`] representation of the object that implements it.
13/// The surface may be created through direct construction or as the result of some computational process.
14///
15/// # Errors
16/// The [`Surfacable::surface`] method returns a [`Result`] containing the generated surface on success.
17/// If an error occurs during the surface generation process, a [`SurfaceError`] is returned instead.
18/// Potential errors could include:
19/// - Invalid inputs or parameters leading to a [`SurfaceError::Point3DError`] or [`SurfaceError::ConstructionError`].
20/// - Failures during surface computation due to invalid operations (e.g., [`SurfaceError::OperationError`]).
21/// - Analysis failures, represented as [`SurfaceError::AnalysisError`].
22///
23/// # Implementors
24/// of this trait should define how their specific type generates a [`Surface`].
25/// This could involve:
26/// - Utilizing existing 3D geometry to build the surface.
27/// - Analytical or procedural computations to construct a surface from data.
28/// - Interactions with external processes or datasets.
29///
30/// # See Also
31/// For more details on specific error variants, refer to the [`SurfaceError`] enum.
32/// For details about the underlying mathematical representation, refer to the [`Surface`] struct.
33///
34/// # Example Use Cases
35/// This trait can be used in scenarios where multiple types need to provide a unified interface
36/// for surface generation. For instance, different shapes (spheres, planes, or curves) may implement
37/// `Surfacable` so that they can all produce [`Surface`] outputs in a consistent manner.
38///
39/// # Related Modules
40/// - **`crate::surfaces::surface`**: Contains the [`Surface`] structure and its related components.
41/// - **`crate::error::surfaces`**: Contains the [`SurfaceError`] type and its variants for error representation.
42///
43pub trait Surfacable {
44 /// - `surface()`:
45 /// - Returns: `Result<Surface, SurfaceError>`
46 /// - Description: Generates a surface or returns an error if something goes wrong during the process.
47 ///
48 /// # Errors
49 ///
50 /// Returns [`SurfaceError::ConstructionError`] when the
51 /// implementor cannot produce any `(x, y, z)` sample
52 /// (empty data source, degenerate axes, or missing metric), and
53 /// propagates [`SurfaceError::Point3DError`] when a sample
54 /// cannot be represented as a `Point3D`.
55 fn surface(&self) -> Result<Surface, SurfaceError>;
56}