Struct Point3D 

pub struct Point3D {
    pub x: Decimal,
    pub y: Decimal,
    pub z: Decimal,
}

Represents a point in three-dimensional space with x, y and z coordinates.

Overview

The Point3D struct defines a point in a 3D Cartesian coordinate system. All coordinates (x, y, and z) are stored as Decimal values to provide high precision, making it suitable for applications requiring accurate numerical calculations.

Fields

• x: The x-coordinate of the point, represented as a Decimal
• y: The y-coordinate of the point, represented as a Decimal
• z: The z-coordinate of the point, represented as a Decimal

Examples

use rust_decimal_macros::dec;
use optionstratlib_math::surfaces::Point3D;

// Create a new 3D point
let point = Point3D {
    x: dec!(1.5),
    y: dec!(2.0),
    z: dec!(-3.25),
};

Usage

Point3D is primarily used within the surface module to represent vertices of 3D surfaces and for various geometric calculations. The high-precision Decimal type ensures accuracy in scientific and engineering applications.

Fields

x: Decimal

The x-coordinate in the Cartesian system

y: Decimal

The y-coordinate in the Cartesian system

z: Decimal

The z-coordinate in the Cartesian system

Implementations

impl Point3D

pub fn new<T: Into<Decimal>, U: Into<Decimal>, V: Into<Decimal>>( x: T, y: U, z: V, ) -> Self

Creates a new instance of Point3D using the specified coordinates.

Parameters

• x: The x-coordinate, which implements Into<Decimal>
• y: The y-coordinate, which implements Into<Decimal>
• z: The z-coordinate, which implements Into<Decimal>

pub fn to_tuple<T: TryFrom<Decimal> + 'static, U: TryFrom<Decimal> + 'static, V: TryFrom<Decimal> + 'static>( &self, ) -> Result<(T, U, V), SurfaceError>

Converts the Point3D to a tuple of three values.

Type Parameters

• T: Type for x-coordinate
• U: Type for y-coordinate
• V: Type for z-coordinate

Errors

Returns SurfaceError::Point3DError in three situations:

• when one of the target types is Positive-like (detected via the is_positive::<T>() / is_positive::<U>() / is_positive::<V>() checks) and the corresponding coordinate is less than or equal to zero.
• when one of the Decimal coordinates cannot be converted into the target numeric type (e.g. out-of-range for f32, overflow for u32).

pub fn from_tuple<T: Into<Decimal>, U: Into<Decimal>, V: Into<Decimal>>( x: T, y: U, z: V, ) -> Result<Self, SurfaceError>

Creates a Point3D from a tuple of three values.

Errors

Currently infallible for the blanket Into<Decimal> bounds; the Result signature is retained so future implementations that can reject non-finite or out-of-range inputs (e.g. via TryFrom<f64>) can surface SurfaceError::Point3DError without a breaking change.

pub fn to_f64_tuple(&self) -> Result<(f64, f64, f64), SurfaceError>

Converts the Point3D to a tuple of f64 values.

Errors

Returns SurfaceError::Point3DError when any coordinate cannot be represented as an f64 (typically a Decimal magnitude that exceeds the f64 range).

pub fn from_f64_tuple(x: f64, y: f64, z: f64) -> Result<Self, SurfaceError>

Creates a Point3D from a tuple of f64 values.

Errors

Returns SurfaceError::Point3DError when any of x, y or z is NaN or infinite and therefore not representable as a Decimal.

pub fn point2d(&self) -> Box<Point2D>

Converts this Point3D instance to a Point2D by projecting onto the XY plane.

Overview

This method creates a new Point2D instance using only the x and y coordinates of the current Point3D object, effectively projecting the 3D point onto the XY plane. The z coordinate is discarded in this operation.

Returns

A heap-allocated Point2D instance (Box<Point2D>) containing the x and y coordinates from this Point3D object.

Example

use rust_decimal_macros::dec;
use optionstratlib_math::surfaces::Point3D;

let point3d = Point3D { x: dec!(1.5), y: dec!(2.0), z: dec!(3.5) };
let point2d = point3d.point2d();
assert_eq!(point2d.x, dec!(1.5));
assert_eq!(point2d.y, dec!(2.0));

Use Cases

This method is useful when:

• Working with visualization that requires 2D projections of 3D points
• Analyzing specific planes within a 3D model
• Converting between coordinate systems from 3D to 2D

Trait Implementations

impl AxisOperations<Point3D, Point2D> for Surface

fn contains_point(&self, x: &Point2D) -> bool

Reports whether any point sits above the xy-coordinate x.

Answers on the (x, y) pair alone, so it says nothing about how many heights are stacked there. On a surface honouring the one-height-per-cell rule of Surface::new there is at most one.

fn get_index_values(&self) -> Vec<Point2D>

Returns the xy-coordinate of every point, in (x, y, z) order.

A surface holding several heights above one cell yields that cell once per height; the duplicates are visible here rather than dropped.

fn get_values(&self, x: Point2D) -> Vec<&Decimal>

Returns every z above the xy-coordinate x, in ascending order.

This is the multi-valued reader: unlike Self::get_point, it never picks a survivor. A surface honouring the one-height-per-cell rule of Surface::new returns at most one value; anything longer says the surface is not a function of its xy-coordinate.

fn get_point(&self, x: &Point2D) -> Option<&Point3D>

Returns the point above the xy-coordinate x, if there is one.

Assumes the one-height-per-cell rule of Surface::new. If the surface breaks it, this returns the first match in (x, y, z) order, which is the lowest z of the stack, and the rest are invisible to the caller. Use Self::get_values to see all of them.

type Error = SurfaceError

The type of error that can occur during point operations

fn get_closest_point(&self, x: &Point2D) -> Result<&Point3D, Self::Error>

Finds the closest point to the given coordinate value.

fn merge_indexes(&self, axis: Vec<Input>) -> Vec<Input>

Merges the index values from the current structure with an additional set of indices. This combines self.get_index_values() with the provided axis vector to create a single vector of unique indices.

impl BiLinearInterpolation<Point3D, Point2D> for Surface

fn bilinear_interpolate( &self, xy: Point2D, ) -> Result<Point3D, InterpolationError>

Performs bilinear interpolation to compute a value for the given input.

impl Clone for Point3D

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ComposeSchema for Point3D

fn compose(generics: Vec<RefOr<Schema>>) -> RefOr<Schema>

impl Copy for Point3D

impl CubicInterpolation<Point3D, Point2D> for Surface

fn cubic_interpolate(&self, xy: Point2D) -> Result<Point3D, InterpolationError>

Interpolates a new point on the curve for a given x input value using cubic interpolation.

impl Debug for Point3D

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Point3D

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Point3D

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

Formats the value using the given formatter.

impl Eq for Point3D

impl From<&Point3D> for Point3D

fn from(point: &Point3D) -> Self

Converts to this type from the input type.

impl GeometricObject<Point3D, Point2D> for Surface

Implementation of the GeometricObject trait for the Surface struct.

This implementation provides functionality to create and manipulate 3D surfaces using points in three-dimensional space. It supports construction from explicit point collections or through parametric functions.

Type Parameters

• Uses Point3D as the points that form the surface
• Uses Point2D as the parametric input for surface generation

Methods

• get_points(): Retrieves all points in the surface
• from_vector(): Constructs a surface from a vector of points
• construct(): Creates a surface using different construction methods

Error Handling

Uses SurfaceError for various error conditions, including:

• Empty point collections
• Invalid construction parameters
• Errors during parametric function evaluation

fn get_points(&self) -> BTreeSet<&Point3D>

Returns a borrowed reference to all points in the surface as an ordered set

Returns

• BTreeSet<&Point3D> - A sorted set containing references to all points that define the surface, maintaining the natural ordering of points

Example

use optionstratlib_math::surfaces::{Surface, Point3D};
use std::collections::BTreeSet;
use rust_decimal_macros::dec;
use optionstratlib_math::geometrics::GeometricObject;

// Create a surface with some points
let mut surface = Surface {
    points: BTreeSet::new(),
    x_range: (dec!(0), dec!(10)),
    y_range: (dec!(0), dec!(10)),
};

// Add points to the surface
surface.points.insert(Point3D { x: dec!(1.0), y: dec!(2.0), z: dec!(3.0) });
surface.points.insert(Point3D { x: dec!(4.0), y: dec!(5.0), z: dec!(6.0) });

// Get references to all points in the surface
let points = surface.get_points();
assert_eq!(points.len(), 2);

fn from_vector<T>(points: Vec<T>) -> Self

where T: Into<Point3D> + Clone,

Creates a new Surface from a vector of points that can be converted into Point3D objects.

This method constructs a Surface by converting each point in the input vector to a Point3D and collecting them into an ordered set. It also calculates the x and y coordinate ranges of the points to define the surface’s boundaries.

Type Parameters

• T: A type that can be converted into Point3D via the Into trait and can be cloned.

Parameters

• points: A vector of objects that can be converted to Point3D.

Returns

A new Surface instance containing the converted points and their coordinate ranges.

Example

use optionstratlib_math::surfaces::{Surface, Point3D};
use optionstratlib_math::geometrics::GeometricObject;
use rust_decimal_macros::dec;

// Create points data
let points = vec![
    Point3D { x: dec!(1.0), y: dec!(2.0), z: dec!(3.0) },
    Point3D { x: dec!(4.0), y: dec!(5.0), z: dec!(6.0) }
];

// Create a surface from the points
let surface = Surface::from_vector(points);

// The surface will contain both points and have x_range and y_range calculated automatically
assert_eq!(surface.points.len(), 2);
assert_eq!(surface.x_range, (dec!(1.0), dec!(4.0)));
assert_eq!(surface.y_range, (dec!(2.0), dec!(5.0)));

fn construct<T>(method: T) -> Result<Self, Self::Error>

where Self: Sized, T: Into<ConstructionMethod<Point3D, Point2D, SurfaceError>>,

Constructs a Surface from a given construction method.

This function creates a Surface object from either a set of 3D points or a parametric function.

Parameters

• method - A construction method that can be converted into a ConstructionMethod<Point3D, Point2D, SurfaceError>

Type Parameters

• T - Type that can be converted into a ConstructionMethod<Point3D, Point2D, SurfaceError>

Returns

• Result<Self, Self::Error> - Either a successfully constructed Surface or an error

Errors

• SurfaceError::Point3DError - If an empty points array is provided
• SurfaceError::ConstructionError - If invalid parameters are provided or the parametric function fails

Examples

Creating from existing points

use std::collections::BTreeSet;
use optionstratlib_math::geometrics::{ConstructionMethod, GeometricObject};
use optionstratlib_math::surfaces::{Point3D, Surface};
let points = BTreeSet::from_iter(vec![
    Point3D::new(0, 0, 0),
    Point3D::new(1, 0, 1),
    Point3D::new(0, 1, 1),
]);
let surface = Surface::construct(ConstructionMethod::FromData { points })?;

Creating from a parametric function

use rust_decimal_macros::dec;
use optionstratlib_math::curves::Point2D;
use optionstratlib_math::error::SurfaceError;
use optionstratlib_math::geometrics::{ConstructionMethod, ConstructionParams, GeometricObject};
use optionstratlib_math::surfaces::{Point3D, Surface};
let params = ConstructionParams::D3 {
    x_start: dec!(-1.0),
    x_end: dec!(1.0),
    y_start: dec!(-1.0),
    y_end: dec!(1.0),
    x_steps: 20,
    y_steps: 20,
};

// Parametric function defining a paraboloid: z = x² + y²
let f = Box::new(|p: Point2D| -> Result<Point3D, SurfaceError> {
    Ok(Point3D {
        x: p.x,
        y: p.y,
        z: p.x * p.x + p.y * p.y,
    })
});

let surface = Surface::construct(ConstructionMethod::Parametric { f, params })?;

type Error = SurfaceError

Type alias for any errors that might occur during the construction of the geometric object.

fn vector(&self) -> Vec<&Point>

Returns a Vec containing references to the points that constitute the geometric object. This method simply converts the BTreeSet from get_points into a Vec.

fn to_vector(&self) -> Vec<&Point>

Returns the points of the geometric object as a Vec of references. Equivalent to calling the vector() method.

fn calculate_range<I>(iter: I) -> (Decimal, Decimal)

where I: Iterator<Item = Decimal>,

Calculates the minimum and maximum decimal values from an iterator of decimals.

impl GeometricTransformations<Point3D> for Surface

type Error = SurfaceError

The error type that can be returned by geometric operations.

fn translate(&self, deltas: Vec<&Decimal>) -> Result<Self, Self::Error>

Translates the geometric object by specified amounts along each dimension.

fn scale(&self, factors: Vec<&Decimal>) -> Result<Self, Self::Error>

Scales the geometric object by specified factors along each dimension.

fn intersect_with(&self, other: &Self) -> Result<Vec<Point3D>, Self::Error>

Finds all intersection points between this geometric object and another.

fn derivative_at(&self, point: &Point3D) -> Result<Vec<Decimal>, Self::Error>

Calculates the derivative at a specific point on the geometric object.

fn extrema(&self) -> Result<(Point3D, Point3D), Self::Error>

Finds the extrema (minimum and maximum points) of the geometric object.

fn measure_under(&self, base_value: &Decimal) -> Result<Decimal, Self::Error>

Calculates the area or volume under the geometric object relative to a base value.

impl HasX for Point3D

fn get_x(&self) -> Decimal

Returns the X-coordinate value of this object.

impl Hash for Point3D

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Interpolate<Point3D, Point2D> for Surface

Implementation of the Interpolate trait for the Surface type, enabling interpolation from 3D surface points to 2D points.

Overview

This implementation allows a Surface object to perform various types of interpolation (linear, bilinear, cubic, and spline) by projecting 3D points from the surface to 2D points.

Functionality

By implementing the Interpolate trait, Surface gains the following capabilities:

• Interpolating between 3D surface points to produce 2D projections
• Finding bracket points for interpolation operations
• Supporting multiple interpolation algorithms through the trait’s methods

Usage Example

use rust_decimal_macros::dec;
use optionstratlib_math::surfaces::{Surface, Point3D};
use optionstratlib_math::curves::Point2D;
use optionstratlib_math::geometrics::{Interpolate, InterpolationType};

let surface = Surface::new(Default::default());

// Interpolate a 2D point at a specific position using linear interpolation
let input_point = Point2D { x: dec!(1.5), y: dec!(2.0) };
let result = surface.interpolate(input_point, InterpolationType::Linear);

Related Traits

This implementation relies on the surface also implementing:

• LinearInterpolation<Point3D, Point2D>
• BiLinearInterpolation<Point3D, Point2D>
• CubicInterpolation<Point3D, Point2D>
• SplineInterpolation<Point3D, Point2D>
• GeometricObject<Point3D, Point2D>

fn interpolate( &self, x: Input, interpolation_type: InterpolationType, ) -> Result<Point, InterpolationError>

Interpolates a value at the given x-coordinate using the specified interpolation method.

fn find_bracket_points( &self, x: Input, ) -> Result<(usize, usize), InterpolationError>

Finds the indices of points that bracket the given x-coordinate.

impl LinearInterpolation<Point3D, Point2D> for Surface

Linear Interpolation for Surfaces

Implementation of the LinearInterpolation trait for Surface structures, enabling interpolation from 2D points to 3D points using barycentric coordinates.

Overview

This implementation allows calculating the height (z-coordinate) of any point within the surface’s x-y range by using linear interpolation based on the three nearest points in the surface. The method employs barycentric coordinate interpolation with triangulation of the nearest points.

Algorithm

The interpolation process follows these steps:

1. Validate that the input point is within the surface’s range
2. Check for degenerate cases (all points at same location)
3. Check for exact matches with existing points
4. Find the three nearest points to the query point
5. Calculate barycentric coordinates for the triangle formed by these points
6. Interpolate the z-value using the barycentric weights

fn linear_interpolate(&self, xy: Point2D) -> Result<Point3D, InterpolationError>

Parameters

• xy - A Point2D representing the x and y coordinates where interpolation is needed

Returns

• Result<Point3D, InterpolationError> - The interpolated 3D point if successful, or an appropriate error if interpolation cannot be performed

Errors

Returns InterpolationError::Linear in the following cases:

• When the surface contains only coincident points forming a degenerate triangle
• When the query point is outside the surface’s x-y range

impl MergeAxisInterpolate<Point3D, Point2D> for Surface

where Self: Sized,

fn merge_axis_interpolate( &self, other: &Self, interpolation: InterpolationType, ) -> Result<(Self, Self), Self::Error>

Resamples both surfaces onto the shared xy-grid of their merged indices.

Each result holds one z per cell of that grid, so it is a function of its xy-coordinate whatever the inputs were: where a surface already covers a cell, the point kept is the first match in (x, y, z) order, so a stack of heights above one cell collapses to its lowest. Aggregate such a surface before merging if a different height is wanted.

fn merge_axis_index<'a>(&'a self, other: &'a Self) -> Vec<Input>

Merges the index values from two structures into a single ordered vector.

impl Ord for Point3D

Orders on (x, y, z), lexicographically: the same triple PartialEq reads, so cmp returns Ordering::Equal exactly when the points are equal.

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for Point3D

Two points are equal when all three coordinates are equal.

PartialEq, Ord and Hash all read the full (x, y, z) triple, so a == b holds exactly when a.cmp(&b) is Ordering::Equal, and equal points hash alike, as Ord requires.

The “one z per (x, y)” rule is a property of a surface, not of a point, and it is a container-level invariant that nothing enforces: crate::surfaces::Surface::new retains a repeated (x, y) coordinate, and points is a pub field, so no constructor could. The rule and what each consumer does when it is broken are documented on crate::surfaces::Surface::new.

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Point3D

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Point3D

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl SplineInterpolation<Point3D, Point2D> for Surface

fn spline_interpolate(&self, xy: Point2D) -> Result<Point3D, InterpolationError>

Interpolates a y-value for the provided x-coordinate using spline interpolation.

impl ToSchema for Point3D

fn name() -> Cow<'static, str>

Return name of the schema.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implement reference utoipa::openapi::schema::Schemas for this type.