Expand description
A general purpose spherical/solid harmonics library in Rust.
This crate offers real and complex spherical harmonics and solid harmonics.
Documentation:
Usage
Add this to your Cargo.toml
:
[dependencies]
sphrs = "0.2.2"
Tutorial
There are two enums RealSH
and ComplexSH
, each with the following variants:
Spherical
RegularSolid
IrregularSolid
These variants are used to define which kind of spherical/solid harmonic is to be computed.
Each enum implements the SHEval
trait, which provides an SHEval::eval
method.
This method is used to compute the spherical/solid harmonic for Coordinates
.
Coordinates define a position in space and can be constructed from Cartesian and spherical
coordinates via Coordinates::cartesian
and Coordinates::spherical
, respectively.
In order to compute real valued spherical harmonics, one needs to call the
eval
method on the Spherical
variant of the RealSH
enum.
The eval
method is part of the SHEval
trait and as such this trait must be in scope.
use sphrs::{Coordinates, RealSH, SHEval};
// l = 2
let degree = 2;
// m = 1
let order = 1;
// Define the position where the SH will be evaluated at
// in Cartesian coordinates
let p = Coordinates::cartesian(1.0, 0.2, 1.4);
// Compute the real-valued SH value at `p` for l = 2, m = 1
let computed_sh = RealSH::Spherical.eval(degree, order, &p);
println!("SH ({}, {}): {:?}", degree, order, computed_sh);
This library can also compute HarmonicsSet
s which contains all spherical/solid harmonics
up to a given order.
The following example shows how to compute complex spherical harmonics up to third order at the spherical coordinates (r, theta, phi) = (1.0, 0.8, 0.4):
use sphrs::{ComplexSH, Coordinates, HarmonicsSet};
// l = 3
let degree = 3;
// Create the harmonics set (in this case for complex SH)
let sh = HarmonicsSet::new(degree, ComplexSH::Spherical);
// Position in spherical coordinates where the set is evaluated at
let p = Coordinates::spherical(1.0, 0.8, 0.4);
// Evaluate. Returns a `Vec<f64>`
let set = sh.eval(&p);
println!("SH up to degree {}: {:?}", degree, set);
The individual SH in the set can also be multiplied element-wise with a vector of coefficients
with the function HarmonicsSet::eval_with_coefficients
:
let sh = HarmonicsSet::new(degree, ComplexSH::Spherical);
// Must be the same length as the set.
let coeff = vec![2.0; sh.num_sh()];
let set = sh.eval_with_coefficients(&p, coeff.as_slice());
println!("SH up to degree {}: {:?}", degree, set);
Advanced features
Feel free to directly use the low level functions linked at the bottom of this page.
Acknowledgements
This crate is heavily inspired by Google’s spherical-harmonics library and follows the design documented here.
References
- Robin Green, “Spherical Harmonic Lighting: The Gritty Details”
- Spherical harmonics (Wikipedia)
- Solid harmonics (Wikipedia)
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Structs
- Representation of coordinates.
- A set of spherical/solid harmonics up to a given degree
Enums
- Available types of complex spherical harmonics and solid harmonics
- Available types of real spherical harmonics and solid harmonics
Traits
- Definition of coordinates
- Harmonics evaluation trait
- Trait alias for trait bounds on floats
Functions
- Complex irregular solid harmonics
- Real irregular solid harmonics
- Real regular solid harmonics
- Real spherical harmonics (recursive implementation)
- Accelerated spherical harmonics.
- Complex regular solid harmonics
- Complex spherical harmonics
- SH (l=0,m=0)
- SH (l=1,m=-1)
- SH (l=1,m=1)
- SH (l=2,m=-1)
- SH (l=2,m=-2)
- SH (l=2,m=1)
- SH (l=2,m=2)
- SH (l=3,m=-1)
- SH (l=3,m=-2)
- SH (l=3,m=-3)
- SH (l=3,m=1)
- SH (l=3,m=2)
- SH (l=3,m=3)
- SH (l=1,m=0)
- SH (l=2,m=0)
- SH (l=3,m=0)