non-riemannian-opt: comparison src/cylinder.rs

-:cac6978dc7dd
+:90cc221eb52b
 pub angle : Angle,
 pub z : f64
 }
 impl CylCoords {
+/// Convert to cartesian coordinates.
 #[inline]
 pub fn to_cartesian(&self) -> Loc<f64, 3> {
 let &CylCoords{r, angle, z} = self;
 [r * angle.cos(), r * angle.sin(), z].into()
 }
+/// Form cylindrical coordinates from cartesian coordinates.
 #[inline]
 #[allow(dead_code)]
 pub fn from_cartesian(coords : Loc<f64, 3>) -> Self {
 let [x, y, z] = coords.into();
 let r = (x*x + y*y).sqrt();
 pub struct SidePoint {
 pub z : f64,
 pub angle : Angle
 }
+/// Calculates the difference between two angles, normalised to [–π, π].
 #[inline]
 fn anglediff(mut φ1 : f64, mut φ2 : f64) -> f64 {
 let π = f64::PI;
 φ1 = normalise_angle(φ1);
 φ2 = normalise_angle(φ2);
 2.0 * π + α
 }
 }
 }
+/// Normalises an angle to [0, 2π].
 #[inline]
 pub fn normalise_angle(φ : f64) -> f64 {
 let π = f64::PI;
 φ.rem_euclid(2.0 * π)
 }
 SidePoint{ z : self.z + h, angle : normalise_angle(self.angle + v / r) }
 }
 }
-/// Point on a [`Cylinder`]
+/// Point on some [`Cylinder`]
 #[derive(Copy, Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub enum Point {
 Top(CapPoint),
 Bottom(CapPoint),
 Side(SidePoint),
 Top,
 Bottom,
 Side,
 }
+/// Point on a specific [`Cylinder`]
 #[derive(Clone, Debug, PartialEq)]
 pub struct OnCylinder<'a> {
+/// Face and coordinates of the point
+point : Point,
+/// The specific cylinder the `point` lies on.
 cylinder : &'a Cylinder,
-point : Point,
 }
 /// Cylinder configuration
 #[derive(Copy, Clone, Debug, PartialEq, Serialize, Deserialize)]
 pub struct CylinderConfig {
+/// Number of Newton iterates two take to solve geodesics.
 pub newton_iters : usize,
 }
 impl Default for CylinderConfig {
 fn default() -> Self {
 write!(f, "{}", s)
 }
 }
 impl Point {
+/// Returns the face of the point
 fn face(&self) -> Face {
 match *self {
 Point::Top(..) => Face::Top,
 Point::Bottom(_) => Face::Bottom,
 Point::Side(_) => Face::Side,
 }
 // Tangent vector
 type Tangent = Loc<f64, 2>;
+/// Goes through list of potential tangents (corresponding to several geodesics taking
+/// different paths), and retuns the shortest tangent vector and the corresponding length.
 #[inline]
 fn best_tangent<I>(tangents : I) -> (Tangent, f64)
 where I : IntoIterator<Item = Tangent> {
 tangents.into_iter()
 .map(|t| (t, t.norm(L2)))
 #[inline]
 fn swap<A>((a, b) : (A, A)) -> (A, A) {
 (b, a)
 }
+/// Indicates whether the `a` and `b` are a distance of less than [`f64::EPSILON`].
 #[inline]
 fn indistinguishable(a : f64, b : f64) -> bool {
 a > b - f64::EPSILON && a < b + f64::EPSILON
 }
 Point::Bottom(cap) => { cap.cyl_coords(self.bottom_z()) },
 Point::Side(side)  => { side.cyl_coords(self.radius) },
 }
 }
+/// Returns the z coordinate of the top (cap) of the cylinder.
 #[inline]
 pub fn top_z(&self) -> f64 {
 self.height / 2.0
 }
+/// Returns the z coordinate of the bottom (cap) of the cylinder.
 #[inline]
 pub fn bottom_z(&self) -> f64 {
 -self.height / 2.0
 }
 /// Find angle where a geodesic from `side` to `(cap, z)` crosses the cap edge.
 ///
-/// Uses `newton_sym1x1`.
+/// Uses [`newton_sym1x1`].
 fn side_cap_crossing(
 &self,
 side : &SidePoint,
 cap : &CapPoint, z : f64, // `z` is the z coordinate of cap
 ) -> Angle {
 }
 /// Find angles where the geodesic passing through a cap at height `z` from `side1` to `side2`
 /// crosses the cap edge. **Panics if `side2.angle < side1.angle`.**
 ///
-/// Uses `newton_sym2x2`.
+/// Uses [`newton_sym2x2`].
 fn side_cap_side_crossing(
 &self,
 side1 : &SidePoint,
 z : f64,
 side2 : &SidePoint
 /// Find angles where the geodesic passing through the side from `cap1` at height `z_1`
 /// to `cap2` at height `z_2` crosses the cap edges.
 /// **Panics if `cap2.angle < cap1.angle`.**
 ///
-/// Uses `newton_sym2x2`.
+/// Uses [`newton_sym2x2`].
 fn cap_side_cap_crossing(
 &self,
 cap1 : &CapPoint, z_1 : f64,
 cap2 : &CapPoint, z_2 : f64,
 init_by_cap2 : bool
 };
 let [α_1, α_2] = newton_sym2x2(f, α_init, self.config.newton_iters);
 (normalise_angle(φ_1 + α_1), normalise_angle(φ_2 - α_2))
 }
+/// Calculates the log between points on a `cap` and a `side` of the cylinder, in this direction.
+/// The `z` coordinate of the cap and an indication whether it is a `top` or bottom cap must
+/// also be given.
 fn cap_side_log(
 &self,
 cap : &CapPoint, (z, top) : (f64, bool),
 side : &SidePoint
 ) -> Tangent {
 (t1/n)*(n + t2.norm(L2))
 }
 }
 }
+/// Calculates the log between points on a `side` and a `cap` of the cylinder, in this direction.
+/// The `z` coordinate of the cap and an indication whether it is a `top` or bottom cap must
+/// also be given.
 fn side_cap_log(
 &self,
 side : &SidePoint,
 cap : &CapPoint, (z, top) : (f64, bool),
 ) -> Tangent {
 (t1/n)*(n + t2.norm(L2))
 }
 }
 }
+/// Calculates the log between points on two sides of the cylinder, assuming the corresonding
+/// geodesic crosses a cap at height `z`. The `top` parameter indicates whether this is a
+/// top cap.
 fn side_cap_side_log(
 &self,
 side1 : &SidePoint,
 (z, top) : (f64, bool),
 side2 : &SidePoint
 (t1/n)*(n + t2.norm(L2) + t3.norm(L2))
 }
 }
 }
+/// Calculates the log between points on two caps of the cylinder, assuming the corresonding
+/// geodesic crosses the side. The heights of the caps and indications whether they are
+/// top caps, must also be given.
 fn cap_side_cap_log(
 &self,
 cap1 : &CapPoint, (z1, top1) : (f64, bool),
 cap2 : &CapPoint, (z2, top2) : (f64, bool),
 init_by_cap2 : bool,
 (t1/n)*(n + t2.norm(L2) + t3.norm(L2))
 }
 }
 }
-/// Calculates both the logarithmic map and distance to another point
+/// Calculates both the logarithmic map and distance between two points.
 fn log_dist(&self, source : &Point, destination : &Point) -> (Tangent, f64) {
 use Point::*;
 match (source, destination) {
 (Top(cap1), Top(cap2)) => {
 best_tangent([cap1.log(cap2)])
 ])
 },
 }
 }
+/// Calculates the exponential map of `point` in the direction `t` until the next edge.
+/// If `t` was fully exhausted before reaching an edge, the second return value is [`None`],
+/// otherwise it is a [`Some`] of the remaining tangent, translated at the returned point.
 #[allow(unreachable_code)]
 #[allow(unused_variables)]
 fn partial_exp(&self, point : Point, t  : Tangent) -> (Point, Option<Tangent>) {
 match point {
 Point::Top(cap) => {
 }
 }
 }
 }
+/// Calculates the exponential map from `point` in the direction of `tangent`.
 fn exp(&self, point : &Point, tangent : &Tangent) -> Point {
 let mut p = *point;
 let mut t = *tangent;
 loop {
 (p, t) = match self.partial_exp(p, t) {
 radius : 1.0,
 height : 1.0,
 config : CylinderConfig { newton_iters : 20 },
 };
+/// Tests for correct distance calculation beween two points on the same cap.
 #[test]
-fn intra_cap_log_dist() {
+fn intra_cap_dist() {
 let π = f64::PI;
 let p1 = CYL.on_top(0.0, 0.5);
 let p2 = CYL.on_top(π, 0.5);
 let p3 = CYL.on_top(π/2.0, 0.5);
 check_distance!(p1.dist_to(&p2), 1.0);
 check_distance!(p2.dist_to(&p3), 0.5_f64.sqrt());
 check_distance!(p3.dist_to(&p1), 0.5_f64.sqrt());
 }
+/// Tests for correct distance calculation beween two points on the side.
 #[test]
-fn intra_side_log_dist() {
+fn intra_side_dist() {
 let π = f64::PI;
 let p1 = CYL.on_side(0.0, 0.0);
 let p2 = CYL.on_side(0.0, 0.4);
 let p3 = CYL.on_side(π/2.0, 0.0);
 check_distance!(p1.dist_to(&p2), 0.4);
 check_distance!(p1.dist_to(&p3), π/2.0*CYL.radius);
 }
+/// Tests for correct distance calculation beween two points on the side, when the corresponding
+/// minimal geodesic has to cross a cap.
 #[test]
-fn intra_side_over_cap_log_dist() {
+fn intra_side_over_cap_dist() {
 let π = f64::PI;
 let off = 0.05;
 let z = CYL.top_z() - off;
 let p1 = CYL.on_side(0.0, z);
 let p2 = CYL.on_side(π, z);
 check_distance!(p1.dist_to(&p2), 2.0 * (CYL.radius + off));
 }
+/// Tests for correct distance calculation between points on top and bottom caps.
 #[test]
-fn top_bottom_log_dist() {
+fn top_bottom_dist() {
 let π = f64::PI;
 let p1 = CYL.on_top(0.0, 0.0);
 let p2 = CYL.on_bottom(0.0, 0.0);
 check_distance!(p1.dist_to(&p2), 2.0 * CYL.radius + CYL.height);
 check_distance!(p1.dist_to(&p2), CYL.radius + CYL.height);
 check_distance!(p1.dist_to(&p3), 2.0 * CYL.radius + CYL.height);
 }
+/// Test for correct distance calculation between points on the side and a cap.
 #[test]
-fn top_side_log_dist() {
+fn top_side_dist() {
 let p1 = CYL.on_top(0.0, 0.0);
 let p2 = CYL.on_side(0.0, 0.0);
 check_distance!(p1.dist_to(&p2), CYL.radius + CYL.height / 2.0);
 }
+/// Tests for correct tangent calculation from a cap to the side.
 #[test]
 fn cap_side_partial_exp() {
 let π = f64::PI;
 let angles = [0.0, π/2.0, π*5.0/6.0, π*7.0/5.0];
 panic!("No tangent left");
 }
 }
 }
+/// Tests for correct tangent calculation from the side to a cap.
 #[test]
 fn side_top_exp() {
 let π = f64::PI;
 let angles = [0.0, π/2.0, π*5.0/6.0, π*7.0/5.0];

Mercurial > repos > non-riemannian-opt / file comparison

comparison: src/cylinder.rs

src/cylinder.rs