Add Segment and generalize Path

doc/news/segment.rst

@@ -0,0 +1,33 @@
+**Added:**
+
+* Added `Ray` to describe a direction at a point; this unifies some functionality from `SaddleConnection` and `Vertical`.
+
+* Added `Vector::parallel` as a shortcut for the repetetive `Vector::ccw() == COLLINEAR && Vector::orientation() == SAME`.
+
+* Added `Segment` generalizing `SaddleConnection`.
+
+* Added possibility to create `Path` from `Segment` or a sequence of `Segment`
+  (before paths could only be built from saddle connections.)
+
+# Added `Chain::vector()` method to make it easier to cast a chain to vector in Python.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* Fixed hashing of `SaddleConnection`. Before, two saddle connections with different underlying representations as chains that represented the same vector were considered different from each other.
+* <news item>
+
+**Performance:**
+
+* <news item>

libflatsurf/flatsurf/chain.hpp

@@ -48,6 +48,8 @@ class Chain : public Serializable<Chain<Surface>>,
   explicit Chain(const Surface&);
   Chain(const Surface&, HalfEdge);
 
+  const Vector<T>& vector() const;
+
   operator const Vector<T> &() const;
   operator const Vector<exactreal::Arb> &() const;
 

libflatsurf/flatsurf/deformation.hpp

@@ -62,6 +62,9 @@ class Deformation {
   // Return the image of the point under this deformation.
   Point<Surface> operator()(const Point<Surface>&) const;
 
+  // Return the image of this ray under the deformation.
+  Ray<Surface> operator()(const Ray<Surface>&) const;
+
   // Return the result of the deformation.
   [[deprecated("Use codomain().clone() instead.")]] Surface surface();
 

libflatsurf/flatsurf/detail/vector_exact.hpp

@@ -40,6 +40,9 @@ class VectorExact : public VectorBase<Vector>,
 
   CCW ccw(const Vector &) const;
   ORIENTATION orientation(const Vector &) const;
+  // Return whether this vector is parallel to the given vector, i.e., whether
+  // the vectors are collinear and euqally oriented.
+  bool parallel(const Vector&) const;
   bool insideCircumcircle(std::initializer_list<Vector>) const;
 
   // Return the scalar product with the argument

libflatsurf/flatsurf/flatsurf.hpp

@@ -1,7 +1,7 @@
 /**********************************************************************
  *  This file is part of flatsurf.
  *
- *        Copyright (C) 2019-2020 Julian Rüth
+ *        Copyright (C) 2019-2022 Julian Rüth
  *
  *  Flatsurf is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
@@ -72,6 +72,8 @@
 #include "saddle_connections_iterator.hpp"
 #include "saddle_connections_sample.hpp"
 #include "saddle_connections_sample_iterator.hpp"
+#include "segment.hpp"
+#include "segment_iterator.hpp"
 #include "serializable.hpp"
 #include "tracked.hpp"
 #include "vector.hpp"

libflatsurf/flatsurf/fmt.hpp

@@ -108,5 +108,11 @@ template <typename Surface>
 struct fmt::formatter<::flatsurf::Path<Surface>> : ::flatsurf::GenericFormatter<::flatsurf::Path<Surface>> {};
 template <typename Surface>
 struct fmt::formatter<::flatsurf::PathIterator<Surface>> : ::flatsurf::GenericFormatter<::flatsurf::PathIterator<Surface>> {};
+template <typename Surface>
+struct fmt::formatter<::flatsurf::Ray<Surface>> : ::flatsurf::GenericFormatter<::flatsurf::Ray<Surface>> {};
+template <typename Surface>
+struct fmt::formatter<::flatsurf::Segment<Surface>> : ::flatsurf::GenericFormatter<::flatsurf::Segment<Surface>> {};
+template <typename Surface>
+struct fmt::formatter<::flatsurf::SegmentIterator<Surface>> : ::flatsurf::GenericFormatter<::flatsurf::SegmentIterator<Surface>> {};
 
 #endif

libflatsurf/flatsurf/forward.hpp

@@ -134,6 +134,9 @@ struct PrivateConstructor {};
 
 struct ProtectedConstructor {};
 
+template <typename Surface>
+class Ray;
+
 template <typename Surface>
 class SaddleConnection;
 
@@ -155,6 +158,12 @@ class SaddleConnectionsSample;
 template <typename Surface>
 class SaddleConnectionsSampleIterator;
 
+template <typename Surface>
+class Segment;
+
+template <typename Surface>
+class SegmentIterator;
+
 template <typename T>
 class Serializable;
 

libflatsurf/flatsurf/path.hpp

@@ -1,7 +1,7 @@
 /**********************************************************************
  *  This file is part of flatsurf.
  *
- *        Copyright (C) 2021 Julian Rüth
+ *        Copyright (C) 2021-2022 Julian Rüth
  *
  *  Flatsurf is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
@@ -22,36 +22,48 @@
 
 #include <boost/operators.hpp>
 #include <iosfwd>
+#include <optional>
 #include <vector>
 
 #include "copyable.hpp"
 #include "serializable.hpp"
 
 namespace flatsurf {
 
-// A connected list of SaddleConnections in a Surface.
+// A connected list of Segments in a Surface.
 template <typename Surface>
 class Path : public Serializable<Path<Surface>>,
              boost::equality_comparable<Path<Surface>> {
-  using Segment = SaddleConnection<Surface>;
   using T = typename Surface::Coordinate;
 
  public:
   Path() noexcept;
-  Path(const Segment&);
-  Path(const std::vector<Segment>&);
+  Path(const Segment<Surface>&);
+  Path(const std::vector<Segment<Surface>>&);
 
-  operator const std::vector<Segment> &() const;
+  [[deprecated("crete a path from the .segment() of a saddle connection instead")]]
+  Path(const SaddleConnection<Surface>&);
+  [[deprecated("crete a path from the sequence of .segment() of a saddle connections instead")]]
+  Path(const std::vector<SaddleConnection<Surface>>&);
 
+  [[deprecated("a path cannot always be converted to a sequence of saddle connections; convert to a vector of segments instead")]]
+  operator const std::vector<SaddleConnection<Surface>> &() const;
+
+  operator const std::vector<Segment<Surface>> &() const;
+
+  // Return whether two paths are indistinguishable, i.e., they are made up of
+  // the same sequence of segments.
   bool operator==(const Path&) const;
 
   // Return whether the path is cyclic, i.e., the last element joins up with the first.
   bool closed() const;
 
   // Return whether there are no segments showing up more than once.
+  // TODO: We need to consider partial segments here.
   bool simple() const;
 
   // Return whether there are no segments followed by their negatives.
+  // TODO: We need to consider partial segments here.
   bool reduced() const;
 
   // Return whether the two paths are equivalent in homotopy.
@@ -80,8 +92,18 @@ class Path : public Serializable<Path<Surface>>,
   // connections in reverse order.
   Path operator-() const;
 
-  void push_front(const Segment&);
-  void push_back(const Segment&);
+  // Return a single segment that is equivalent to this path.
+  // Return nullopt if this path is not made up of segments that join up to a
+  // single segment.
+  std::optional<Segment<Surface>> segment() const;
+
+  void push_front(const Segment<Surface>&);
+  void push_back(const Segment<Surface>&);
+
+  [[deprecated("push the saddle connection's .segment() instead")]]
+  void push_front(const SaddleConnection<Surface>&);
+  [[deprecated("push the saddle connection's .segment() instead")]]
+  void push_back(const SaddleConnection<Surface>&);
 
   void pop_front();
   void pop_back();
@@ -103,7 +125,9 @@ class Path : public Serializable<Path<Surface>>,
 
   friend ImplementationOf<Path>;
   friend iterator;
+  friend SegmentIterator<Surface>;
   friend ImplementationOf<iterator>;
+  friend ImplementationOf<SegmentIterator<Surface>>;
 };
 
 template <typename Surface>
@@ -113,4 +137,5 @@ template <typename Surface>
 Path(const SaddleConnection<Surface>&) -> Path<Surface>;
 
 }  // namespace flatsurf
+
 #endif

libflatsurf/flatsurf/path_iterator.hpp

@@ -1,7 +1,7 @@
 /**********************************************************************
  *  This file is part of flatsurf.
  *
- *        Copyright (C) 2020 Julian Rüth
+ *        Copyright (C) 2020-2022 Julian Rüth
  *
  *  Flatsurf is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
@@ -30,7 +30,7 @@ namespace flatsurf {
 
 // Iterates over a path in a surface, i.e., over a connected sequence of saddle connections.
 template <typename Surface>
-class PathIterator : public boost::iterator_facade<PathIterator<Surface>, const SaddleConnection<Surface>&, boost::forward_traversal_tag> {
+class [[deprecated("use SegmentIterator instead")]] PathIterator : public boost::iterator_facade<PathIterator<Surface>, const SaddleConnection<Surface>&, boost::forward_traversal_tag> {
   template <typename... Args>
   PathIterator(PrivateConstructor, Args&&...);
 
@@ -41,6 +41,9 @@ class PathIterator : public boost::iterator_facade<PathIterator<Surface>, const
   const value_type& dereference() const;
   bool equal(const PathIterator& other) const;
 
+  operator const SegmentIterator<Surface>() const;
+  operator SegmentIterator<Surface>();
+
   template <typename S>
   friend std::ostream& operator<<(std::ostream&, const PathIterator<S>&);
 

libflatsurf/flatsurf/ray.hpp

@@ -0,0 +1,107 @@
+/**********************************************************************
+ *  This file is part of flatsurf.
+ *
+ *        Copyright (C) 2022 Julian Rüth
+ *
+ *  Flatsurf is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  Flatsurf is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with flatsurf. If not, see <https://www.gnu.org/licenses/>.
+ *********************************************************************/
+
+#ifndef LIBFLATSURF_RAY_HPP
+#define LIBFLATSURF_RAY_HPP
+
+#include <boost/operators.hpp>
+#include <iosfwd>
+#include <type_traits>
+
+#include "copyable.hpp"
+#include "serializable.hpp"
+
+namespace flatsurf {
+
+// A ray starting at a point of a translation surface.
+template <typename Surface>
+class Ray : Serializable<Ray<Surface>>,
+            boost::equality_comparable<Ray<Surface>> {
+  static_assert(std::is_same_v<Surface, std::decay_t<Surface>>, "type must not have modifiers such as const");
+
+  using T = typename Surface::Coordinate;
+
+ public:
+  Ray(const Point<Surface>&, const Vector<T>&);
+  Ray(const Point<Surface>&, HalfEdge source, const Vector<T>&);
+  Ray(const Surface&, HalfEdge source, const Vector<T>&);
+  Ray(const Surface&, HalfEdge);
+
+  const Point<Surface>& start() const;
+
+  // Return a source half edge for this ray.
+  // This is only really meaningful if start() is a vertex. In that case it
+  // returns one of the outgoing half edges of the vertex such that the
+  // vector() is inSector().
+  // If start() is on an edge, returns the half edge corresponding to the face
+  // into which the vector points (if parallel to the edge, then the half edge
+  // that is parallel to the vector.)
+  // If start() is in a face, returns a half edge such that vector or -vector
+  // is inSector of that half edge.
+  HalfEdge source() const;
+
+  // Return a vector pointing in the direction of this ray.
+  explicit operator const Vector<T> &() const;
+
+  // Return a vector pointing in the direction of this ray.
+  const Vector<T>& vector() const;
+
+  operator Vertical<Surface>() const;
+
+  // Return the saddle connection obtained by extending this ray.
+  SaddleConnection<Surface> saddleConnection() const;
+
+  // Return the turns between two rays starting at the same point.
+  // If the angle between this ray and the argument is α going
+  // in counter-clockwise direction, returns ⌊α/2π⌋.
+  int angle(const Ray&) const;
+
+  // Return the turn direction between rays.
+  // Returns whether it is shorter to turn in counterclockwise or
+  // clockwise direction. Returns COLLINEAR if both are the same.
+  CCW ccw(const Ray&) const;
+
+  // Return whether two rays are the same, i.e., they are pointing in the same
+  // direction from the same starting point.
+  bool operator==(const Ray&) const;
+
+  const Surface &surface() const;
+
+  // Return the segment obtained by following this ray until ``end``.
+  Segment<Surface> segment(const Point<Surface>& end) const;
+
+  template <typename S>
+  friend std::ostream &operator<<(std::ostream &, const Ray<S> &);
+
+ private:
+  Copyable<Ray> self;
+
+  friend ImplementationOf<Ray>;
+};
+
+template <typename Surface, typename... Args>
+Ray(const Surface &, Args &&...) -> Ray<Surface>;
+
+template <typename Surface, typename... Args>
+Ray(const Point<Surface>&, Args &&...) -> Ray<Surface>;
+
+}  // namespace flatsurf
+
+#endif
+