@sentryware/s2-node 0.0.6

package/third_party/s2geometry/src/s2/s2polyline_alignment.cc

@@ -0,0 +1,414 @@
+// Copyright 2017 Google Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+
+#include "s2/s2polyline_alignment.h"
+#include "s2/s2polyline_alignment_internal.h"
+
+#include <algorithm>
+#include <numeric>
+#include <sstream>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include "s2/base/logging.h"
+#include "s2/third_party/absl/memory/memory.h"
+#include "s2/util/math/mathutil.h"
+
+namespace s2polyline_alignment {
+
+Window::Window(const std::vector<ColumnStride>& strides) {
+  S2_DCHECK(!strides.empty()) << "Cannot construct empty window.";
+  S2_DCHECK(strides[0].start == 0) << "First element of start_cols is non-zero.";
+  strides_ = strides;
+  rows_ = strides.size();
+  cols_ = strides.back().end;
+  S2_DCHECK(this->IsValid()) << "Constructor validity check fail.";
+}
+
+Window::Window(const WarpPath& warp_path) {
+  S2_DCHECK(!warp_path.empty()) << "Cannot construct window from empty warp path.";
+  S2_DCHECK(warp_path.front() == std::make_pair(0, 0)) << "Must start at (0, 0).";
+  rows_ = warp_path.back().first + 1;
+  S2_DCHECK(rows_ > 0) << "Must have at least one row.";
+  cols_ = warp_path.back().second + 1;
+  S2_DCHECK(cols_ > 0) << "Must have at least one column.";
+  strides_.resize(rows_);
+
+  int prev_row = 0;
+  int curr_row = 0;
+  int stride_start = 0;
+  int stride_stop = 0;
+  for (const auto& pair : warp_path) {
+    curr_row = pair.first;
+    if (curr_row > prev_row) {
+      strides_[prev_row] = {stride_start, stride_stop};
+      stride_start = pair.second;
+      prev_row = curr_row;
+    }
+    stride_stop = pair.second + 1;
+  }
+  S2_DCHECK_EQ(curr_row, rows_ - 1);
+  strides_[rows_ - 1] = {stride_start, stride_stop};
+  S2_DCHECK(this->IsValid()) << "Constructor validity check fail.";
+}
+
+Window Window::Upsample(const int new_rows, const int new_cols) const {
+  S2_DCHECK(new_rows >= rows_) << "Upsampling: New_rows < current_rows";
+  S2_DCHECK(new_cols >= cols_) << "Upsampling: New_cols < current_cols";
+  const double row_scale = static_cast<double>(new_rows) / rows_;
+  const double col_scale = static_cast<double>(new_cols) / cols_;
+  std::vector<ColumnStride> new_strides(new_rows);
+  ColumnStride from_stride;
+  for (int row = 0; row < new_rows; ++row) {
+    from_stride = strides_[static_cast<int>((row + 0.5) / row_scale)];
+    new_strides[row] = {static_cast<int>(col_scale * from_stride.start + 0.5),
+                        static_cast<int>(col_scale * from_stride.end + 0.5)};
+  }
+  return Window(new_strides);
+}
+
+// This code takes advantage of the fact that the dilation window is square to
+// ensure that we can compute the stride for each output row in constant time.
+// TODO (mrdmnd): a potential optimization might be to combine this method and
+// the Upsample method into a single "Expand" method. For the sake of
+// testing, I haven't done that here, but I think it would be fairly
+// straightforward to do so. This method generally isn't very expensive so it
+// feels unnecessary to combine them.
+Window Window::Dilate(const int radius) const {
+  S2_DCHECK(radius >= 0) << "Negative dilation radius.";
+  std::vector<ColumnStride> new_strides(rows_);
+  int prev_row, next_row;
+  for (int row = 0; row < rows_; ++row) {
+    prev_row = std::max(0, row - radius);
+    next_row = std::min(row + radius, rows_ - 1);
+    new_strides[row] = {std::max(0, strides_[prev_row].start - radius),
+                        std::min(strides_[next_row].end + radius, cols_)};
+  }
+  return Window(new_strides);
+}
+
+// Debug string implemented primarily for testing purposes.
+string Window::DebugString() const {
+  std::stringstream buffer;
+  for (int row = 0; row < rows_; ++row) {
+    for (int col = 0; col < cols_; ++col) {
+      buffer << (strides_[row].InRange(col) ? " *" : " .");
+    }
+    buffer << std::endl;
+  }
+  return buffer.str();
+}
+
+// Valid Windows require the following structural conditions to hold:
+// 1) All rows must consist of a single contiguous stride of `true` values.
+// 2) All strides are greater than zero length (i.e. no empty rows).
+// 3) The index of the first `true` column in a row must be at least as
+//    large as the index of the first `true` column in the previous row.
+// 4) The index of the last `true` column in a row must be at least as large
+//    as the index of the last `true` column in the previous row.
+// 5) strides[0].start = 0 (the first cell is always filled).
+// 6) strides[n_rows-1].end = n_cols (the last cell is filled).
+bool Window::IsValid() const {
+  if (rows_ <= 0 || cols_ <= 0 || strides_.front().start != 0 ||
+      strides_.back().end != cols_) {
+    return false;
+  }
+
+  ColumnStride prev = {-1, -1};
+  for (const auto& curr : strides_) {
+    if (curr.end <= curr.start || curr.start < prev.start ||
+        curr.end < prev.end) {
+      return false;
+    }
+    prev = curr;
+  }
+  return true;
+}
+
+inline double BoundsCheckedTableCost(const int row, const int col,
+                                     const ColumnStride& stride,
+                                     const CostTable& table) {
+  if (row < 0 && col < 0) {
+    return 0.0;
+  } else if (row < 0 || col < 0 || !stride.InRange(col)) {
+    return DOUBLE_MAX;
+  } else {
+    return table[row][col];
+  }
+}
+
+// Perform dynamic timewarping by filling in the DP table on cells that are
+// inside our search window. For an exact (all-squares) evaluation, this
+// incurs bounds checking overhead - we don't need to ensure that we're inside
+// the appropriate cells in the window, because it's guaranteed. Structuring
+// the program to reuse code for both the EXACT and WINDOWED cases by
+// abstracting EXACT as a window with full-covering strides is done for
+// maintainability reasons. One potential optimization here might be to overload
+// this function to skip bounds checking when the window is full.
+//
+// As a note of general interest, the Dynamic Timewarp algorithm as stated here
+// prefers shorter warp paths, when two warp paths might be equally costly. This
+// is because it favors progressing in the sequences simultaneously due to the
+// equal weighting of a diagonal step in the cost table with a horizontal or
+// vertical step. This may be counterintuitive, but represents the standard
+// implementation of this algorithm. TODO(user) - future implementations could
+// allow weights on the lookup costs to mitigate this.
+//
+// This is the hottest routine in the whole package, please be careful to
+// profile any future changes made here.
+//
+// This method takes time proportional to the number of cells in the window,
+// which can range from O(max(a, b)) cells (best) to O(a*b) cells (worst)
+VertexAlignment DynamicTimewarp(const S2Polyline& a, const S2Polyline& b,
+                                const Window& w) {
+  const int rows = a.num_vertices();
+  const int cols = b.num_vertices();
+  auto costs = CostTable(rows, std::vector<double>(cols));
+
+  ColumnStride curr;
+  ColumnStride prev = ColumnStride::All();
+  for (int row = 0; row < rows; ++row) {
+    curr = w.GetColumnStride(row);
+    for (int col = curr.start; col < curr.end; ++col) {
+      double d_cost = BoundsCheckedTableCost(row - 1, col - 1, prev, costs);
+      double u_cost = BoundsCheckedTableCost(row - 1, col - 0, prev, costs);
+      double l_cost = BoundsCheckedTableCost(row - 0, col - 1, curr, costs);
+      costs[row][col] = std::min({d_cost, u_cost, l_cost}) +
+                        (a.vertex(row) - b.vertex(col)).Norm2();
+    }
+    prev = curr;
+  }
+
+  // Now we walk back through the cost table and build up the warp path.
+  // Somewhat surprisingly, it is faster to recover the path this way than it
+  // is to save the comparisons from the computation we *already did* to get the
+  // direction we came from. The author speculates that this behavior is
+  // assignment-cost-related: to persist direction, we have to do extra
+  // stores/loads of "directional" information, and the extra assignment cost
+  // this incurs is larger than the cost to simply redo the comparisons.
+  // It's probably worth revisiting this assumption in the future.
+  // As it turns out, the following code ends up effectively free.
+  WarpPath warp_path;
+  warp_path.reserve(std::max(a.num_vertices(), b.num_vertices()));
+  int row = a.num_vertices() - 1;
+  int col = b.num_vertices() - 1;
+  curr = w.GetCheckedColumnStride(row);
+  prev = w.GetCheckedColumnStride(row - 1);
+  while (row >= 0 && col >= 0) {
+    warp_path.push_back({row, col});
+    double d_cost = BoundsCheckedTableCost(row - 1, col - 1, prev, costs);
+    double u_cost = BoundsCheckedTableCost(row - 1, col - 0, prev, costs);
+    double l_cost = BoundsCheckedTableCost(row - 0, col - 1, curr, costs);
+    if (d_cost <= u_cost && d_cost <= l_cost) {
+      row -= 1;
+      col -= 1;
+      curr = w.GetCheckedColumnStride(row);
+      prev = w.GetCheckedColumnStride(row - 1);
+    } else if (u_cost <= l_cost) {
+      row -= 1;
+      curr = w.GetCheckedColumnStride(row);
+      prev = w.GetCheckedColumnStride(row - 1);
+    } else {
+      col -= 1;
+    }
+  }
+  std::reverse(warp_path.begin(), warp_path.end());
+  return VertexAlignment(costs.back().back(), warp_path);
+}
+
+std::unique_ptr<S2Polyline> HalfResolution(const S2Polyline& in) {
+  const int n = in.num_vertices();
+  std::vector<S2Point> vertices;
+  vertices.reserve(n / 2);
+  for (int i = 0; i < n; i += 2) {
+    vertices.push_back(in.vertex(i));
+  }
+  return absl::make_unique<S2Polyline>(vertices);
+}
+
+// Helper methods for GetMedoidPolyline and GetConsensusPolyline to auto-select
+// appropriate cost function / alignment functions.
+double CostFn(const S2Polyline& a, const S2Polyline& b, bool approx) {
+  return approx ? GetApproxVertexAlignment(a, b).alignment_cost
+                : GetExactVertexAlignmentCost(a, b);
+}
+
+VertexAlignment AlignmentFn(const S2Polyline& a, const S2Polyline& b,
+                            bool approx) {
+  return approx ? GetApproxVertexAlignment(a, b)
+                : GetExactVertexAlignment(a, b);
+}
+
+// PUBLIC API IMPLEMENTATION DETAILS
+
+// This is the constant-space implementation of Dynamic Timewarp that can
+// compute the alignment cost, but not the warp path.
+double GetExactVertexAlignmentCost(const S2Polyline& a, const S2Polyline& b) {
+  const int a_n = a.num_vertices();
+  const int b_n = b.num_vertices();
+  S2_CHECK(a_n > 0) << "A is empty polyline.";
+  S2_CHECK(b_n > 0) << "B is empty polyline.";
+  std::vector<double> cost(b_n, DOUBLE_MAX);
+  double left_diag_min_cost = 0;
+  for (int row = 0; row < a_n; ++row) {
+    for (int col = 0; col < b_n; ++col) {
+      double up_cost = cost[col];
+      cost[col] = std::min(left_diag_min_cost, up_cost) +
+                  (a.vertex(row) - b.vertex(col)).Norm2();
+      left_diag_min_cost = std::min(cost[col], up_cost);
+    }
+    left_diag_min_cost = DOUBLE_MAX;
+  }
+  return cost.back();
+}
+
+VertexAlignment GetExactVertexAlignment(const S2Polyline& a,
+                                        const S2Polyline& b) {
+  const int a_n = a.num_vertices();
+  const int b_n = b.num_vertices();
+  S2_CHECK(a_n > 0) << "A is empty polyline.";
+  S2_CHECK(b_n > 0) << "B is empty polyline.";
+  const auto w = Window(std::vector<ColumnStride>(a_n, {0, b_n}));
+  return DynamicTimewarp(a, b, w);
+}
+
+VertexAlignment GetApproxVertexAlignment(const S2Polyline& a,
+                                         const S2Polyline& b,
+                                         const int radius) {
+  // Determined experimentally, through benchmarking, as about the points at
+  // which ExactAlignment is faster than ApproxAlignment, so we use these as
+  // our switchover points to exact computation mode.
+  const int kSizeSwitchover = 32;
+  const double kDensitySwitchover = 0.85;
+  const int a_n = a.num_vertices();
+  const int b_n = b.num_vertices();
+  S2_CHECK(a_n > 0) << "A is empty polyline.";
+  S2_CHECK(b_n > 0) << "B is empty polyline.";
+  S2_CHECK(radius >= 0) << "Radius is negative.";
+
+  // If we've hit the point where doing a full, direct solve is guaranteed to
+  // be faster, then terminate the recursion and do that.
+  if (a_n - radius < kSizeSwitchover || b_n - radius < kSizeSwitchover) {
+    return GetExactVertexAlignment(a, b);
+  }
+
+  // If we've hit the point where the window will be probably be so full that we
+  // might as well compute an exact solution, then terminate recursion to do so.
+  if (std::max(a_n, b_n) * (2 * radius + 1) > a_n * b_n * kDensitySwitchover) {
+    return GetExactVertexAlignment(a, b);
+  }
+
+  // Otherwise, shrink the input polylines, recursively compute the vertex
+  // alignment using this method, and then compute the final alignment using
+  // the projected alignment `proj` on an upsampled, dilated window.
+  const auto a_half = HalfResolution(a);
+  const auto b_half = HalfResolution(b);
+  const auto proj = GetApproxVertexAlignment(*a_half, *b_half, radius);
+  const auto w = Window(proj.warp_path).Upsample(a_n, b_n).Dilate(radius);
+  return DynamicTimewarp(a, b, w);
+}
+
+// This method calls the approx method with a reasonable default for radius.
+VertexAlignment GetApproxVertexAlignment(const S2Polyline& a,
+                                         const S2Polyline& b) {
+  const int max_length = std::max(a.num_vertices(), b.num_vertices());
+  const int radius = static_cast<int>(std::pow(max_length, 0.25));
+  return GetApproxVertexAlignment(a, b, radius);
+}
+
+// We use some of the symmetry of our metric to avoid computing all N^2
+// alignments. Specifically, because cost_fn(a, b) = cost_fn(b, a), and
+// cost_fn(a, a) = 0, we can compute only the lower triangle of cost matrix
+// and then mirror it across the diagonal to save on cost_fn invocations.
+int GetMedoidPolyline(const std::vector<std::unique_ptr<S2Polyline>>& polylines,
+                      const MedoidOptions options) {
+  const int num_polylines = polylines.size();
+  const bool approx = options.approx();
+  S2_CHECK_GT(num_polylines, 0);
+
+  // costs[i] stores total cost of aligning [i] with all other polylines.
+  std::vector<double> costs(num_polylines, 0.0);
+  for (int i = 0; i < num_polylines; ++i) {
+    for (int j = i + 1; j < num_polylines; ++j) {
+      double cost = CostFn(*polylines[i], *polylines[j], approx);
+      costs[i] += cost;
+      costs[j] += cost;
+    }
+  }
+  return std::min_element(costs.begin(), costs.end()) - costs.begin();
+}
+
+// Implements Iterative Dynamic Timewarp Barycenter Averaging algorithm from
+//
+// https://pdfs.semanticscholar.org/a596/8ca9488199291ffe5473643142862293d69d.pdf
+//
+// Algorithm:
+// Initialize consensus sequence with either the medoid or an arbitrary
+// element (chosen here to be the first element in the input collection).
+// While the consensus polyline `consensus` hasn't converged and we haven't
+// exceeded our iteration cap:
+//   For each polyline `p` in the input,
+//     Compute vertex alignment from the current consensus to `p`.
+//     For each (c_index, p_index) pair in the warp path,
+//       Add the S2Point pts->vertex(p_index) to S2Point consensus[c_index]
+//   Normalize (compute centroid) of each consensus point.
+//   Determine if consensus is converging; if no vertex has moved or we've hit
+//   the iteration cap, halt.
+//
+//  This algorithm takes O(iteration_cap * num_polylines) pairwise alignments.
+
+std::unique_ptr<S2Polyline> GetConsensusPolyline(
+    const std::vector<std::unique_ptr<S2Polyline>>& polylines,
+    const ConsensusOptions options) {
+  const int num_polylines = polylines.size();
+  S2_CHECK_GT(num_polylines, 0);
+  const bool approx = options.approx();
+
+  // Seed a consensus polyline, either arbitrarily with first element, or with
+  // the medoid. If seeding with medoid, inherit approx parameter from options.
+  int seed_index = 0;
+  if (options.seed_medoid()) {
+    MedoidOptions medoid_options;
+    medoid_options.set_approx(approx);
+    seed_index = GetMedoidPolyline(polylines, medoid_options);
+  }
+  auto consensus = std::unique_ptr<S2Polyline>(polylines[seed_index]->Clone());
+  const int num_consensus_vertices = consensus->num_vertices();
+  S2_DCHECK_GT(num_consensus_vertices, 1);
+
+  bool converged = false;
+  int iterations = 0;
+  while (!converged && iterations < options.iteration_cap()) {
+    std::vector<S2Point> points(num_consensus_vertices, S2Point());
+    for (const auto& polyline : polylines) {
+      const auto alignment = AlignmentFn(*consensus, *polyline, approx);
+      for (const auto& pair : alignment.warp_path) {
+        points[pair.first] += polyline->vertex(pair.second);
+      }
+    }
+    for (S2Point& p : points) {
+      p = p.Normalize();
+    }
+
+    ++iterations;
+    auto new_consensus = absl::make_unique<S2Polyline>(points);
+    converged = new_consensus->ApproxEquals(*consensus);
+    consensus = std::move(new_consensus);
+  }
+  return consensus;
+}
+}  // namespace s2polyline_alignment

package/third_party/s2geometry/src/s2/s2polyline_alignment.h

@@ -0,0 +1,245 @@
+// Copyright 2017 Google Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+
+#ifndef S2_S2POLYLINE_ALIGNMENT_H_
+#define S2_S2POLYLINE_ALIGNMENT_H_
+
+#include <memory>
+#include <vector>
+
+#include "s2/s2polyline.h"
+
+// This library provides code to compute vertex alignments between S2Polylines.
+//
+// A vertex "alignment" or "warp" between two polylines is a matching between
+// pairs of their vertices. Users can imagine pairing each vertex from
+// S2Polyline `a` with at least one other vertex in S2Polyline `b`. The "cost"
+// of an arbitrary alignment is defined as the summed value of the squared
+// chordal distance between each pair of points in the warp path. An "optimal
+// alignment" for a pair of polylines is defined as the alignment with least
+// cost. Note: optimal alignments are not necessarily unique. The standard way
+// of computing an optimal alignment between two sequences is the use of the
+// `Dynamic Timewarp` algorithm.
+//
+// We provide three methods for computing (via Dynamic Timewarp) the optimal
+// alignment between two S2Polylines. These methods are performance-sensitive,
+// and have been reasonably optimized for space- and time- usage. On modern
+// hardware, it is possible to compute exact alignments between 4096x4096
+// element polylines in ~70ms, and approximate alignments much more quickly.
+//
+// The results of an alignment operation are captured in a VertexAlignment
+// object. In particular, a VertexAlignment keeps track of the total cost of
+// alignment, as well as the warp path (a sequence of pairs of indices into each
+// polyline whose vertices are linked together in the optimal alignment)
+//
+// For a worked example, consider the polylines
+//
+// a = [(1, 0), (5, 0), (6, 0), (9, 0)] and
+// b = [(2, 0), (7, 0), (8, 0)].
+//
+// The "cost matrix" between these two polylines (using squared chordal
+// distance, .Norm2(), as our distance function) looks like this:
+//
+//        (2, 0)  (7, 0)  (8, 0)
+// (1, 0)     1      36      49
+// (5, 0)     9       4       9
+// (6, 0)    16       1       4
+// (9, 0)    49       4       1
+//
+// The Dynamic Timewarp DP table for this cost matrix has cells defined by
+//
+// table[i][j] = cost(i,j) + min(table[i-1][j-1], table[i][j-1], table[i-1, j])
+//
+//        (2, 0)  (7, 0)  (8, 0)
+// (1, 0)     1      37      86
+// (5, 0)    10       5      14
+// (6, 0)    26       6       9
+// (9, 0)    75      10       7
+//
+// Starting at the bottom right corner of the DP table, we can work our way
+// backwards to the upper left corner  to recover the reverse of the warp path:
+// (3, 2) -> (2, 1) -> (1, 1) -> (0, 0). The VertexAlignment produced containing
+// this has alignment_cost = 7 and warp_path = {(0, 0), (1, 1), (2, 1), (3, 2)}.
+//
+// We also provide methods for performing alignment of multiple sequences. These
+// methods return a single, representative polyline from a non-empty collection
+// of polylines, for various definitions of "representative."
+//
+// GetMedoidPolyline() returns a new polyline (point-for-point-equal to some
+// existing polyline from the collection) that minimizes the summed vertex
+// alignment cost to all other polylines in the collection.
+//
+// GetConsensusPolyline() returns a new polyline (unlikely to be present in the
+// input collection) that represents a "weighted consensus" polyline. This
+// polyline is constructed iteratively using the Dynamic Timewarp Barycenter
+// Averaging algorithm of F. Petitjean, A. Ketterlin, and P. Gancarski, which
+// can be found here:
+// https://pdfs.semanticscholar.org/a596/8ca9488199291ffe5473643142862293d69d.pdf
+
+namespace s2polyline_alignment {
+
+typedef std::vector<std::pair<int, int>> WarpPath;
+
+struct VertexAlignment {
+  // `alignment_cost` represents the sum of the squared chordal distances
+  // between each pair of vertices in the warp path. Specifically,
+  // cost = sum_{(i, j) \in path} (a.vertex(i) - b.vertex(j)).Norm2();
+  // This means that the units of alignment_cost are "squared distance". This is
+  // an optimization to avoid the (expensive) atan computation of the true
+  // spherical angular distance between the points, as well as an unnecessary
+  // square root. All we need to compute vertex alignment is a metric that
+  // satisifies the triangle inequality, and squared chordal distance works as
+  // well as spherical S1Angle distance for this purpose.
+  double alignment_cost;
+
+  // Each entry (i, j) of `warp_path` represents a pairing between vertex
+  // a.vertex(i) and vertex b.vertex(j) in the optimal alignment.
+  // The warp_path is defined in forward order, such that the result of
+  // aligning polylines `a` and `b` is always a warp_path with warp_path.front()
+  // = {0,0} and warp_path.back() = {a.num_vertices() - 1, b.num_vertices() - 1}
+  // Note that this DOES NOT define an alignment from a point sequence to an
+  // edge sequence. That functionality may come at a later date.
+  WarpPath warp_path;
+
+  VertexAlignment(const double cost, const WarpPath& path)
+      : alignment_cost(cost), warp_path(path) {}
+};
+
+// GetExactVertexAlignment takes two non-empty polylines as input, and returns
+// the VertexAlignment corresponding to the optimal alignment between them. This
+// method is quadratic O(A*B) in both space and time complexity.
+VertexAlignment GetExactVertexAlignment(const S2Polyline& a,
+                                        const S2Polyline& b);
+
+// GetExactVertexAlignmentCost takes two non-empty polylines as input, and
+// returns the *cost* of their optimal alignment. A standard, traditional
+// dynamic timewarp algorithm can output both a warp path and a cost, but
+// requires quadratic space to reconstruct the path by walking back through the
+// Dynamic Programming cost table. If all you really need is the warp cost (i.e.
+// you're inducing a similarity metric between S2Polylines, or something
+// equivalent), you can overwrite the DP table and use constant space -
+// O(max(A,B)). This method provides that space-efficiency optimization.
+double GetExactVertexAlignmentCost(const S2Polyline& a, const S2Polyline& b);
+
+// GetApproxVertexAlignment takes two non-empty polylines `a` and `b` as input,
+// and a `radius` paramater GetApproxVertexAlignment (quickly) computes an
+// approximately optimal vertex alignment of points between polylines `a` and
+// `b` by implementing the algorithm described in `FastDTW: Toward Accurate
+// Dynamic Time Warping in Linear Time and Space` by Stan Salvador and Philip
+// Chan. Details can be found below:
+//
+// https://pdfs.semanticscholar.org/05a2/0cde15e172fc82f32774dd0cf4fe5827cad2.pdf
+//
+// The `radius` parameter controls the distance we search outside of the
+// projected warp path during the refining step. Smaller values of `radius`
+// correspond to a smaller search window, and therefore distance computation on
+// fewer cells, which leads to a faster (but worse) approximation.
+// This method is O(max(A, B)) in both space and time complexity.
+VertexAlignment GetApproxVertexAlignment(const S2Polyline& a,
+                                         const S2Polyline& b, const int radius);
+
+// A convience overload for GetApproxVertexAlignment which computes and uses
+// suggested default parameter of radius = max(a.size(), b.size())^0.25
+VertexAlignment GetApproxVertexAlignment(const S2Polyline& a,
+                                         const S2Polyline& b);
+
+// GetMedoidPolyline returns the index `p` of a "medoid" polyline from a
+// non-empty collection of `polylines` such that
+//
+// sum_{all j in `polylines`} VertexAlignmentCost(p, j) is minimized.
+//
+// In the case of a tie for minimal summed alignment cost, we return the lowest
+// index - this tie is guaranteed to happen in the two-polyline-input case.
+//
+// ASYMPTOTIC BEHAVIOR:
+// Computation may require up to (N^2 - N) / 2 alignment cost function
+// evaluations, for N input polylines. For polylines of length U, V, the
+// alignment cost function evaluation is O(U+V) if options.approx = true and
+// O(U*V) if options.approx = false.
+
+class MedoidOptions {
+ public:
+  // If options.approx = false, we compute vertex alignment costs exactly.
+  // If options.approx = true, we use approximate vertex alignment
+  // computation, called with the default radius parameter.
+  bool approx() const { return approx_; }
+  void set_approx(bool approx) { approx_ = approx; }
+
+ private:
+  bool approx_ = true;
+};
+
+int GetMedoidPolyline(const std::vector<std::unique_ptr<S2Polyline>>& polylines,
+                      const MedoidOptions options);
+
+// GetConsensusPolyline allocates and returns a new "consensus" polyline from a
+// non-empty collection of polylines. We iteratively apply Dynamic Timewarp
+// Barycenter Averaging to an initial `seed` polyline, which improves the
+// consensus alignment quality each iteration. For implementation details, see
+//
+// https://pdfs.semanticscholar.org/a596/8ca9488199291ffe5473643142862293d69d.pdf
+//
+// The returned polyline from this method is unlikely to be point-for-point
+// equal to an input polyline, whereas a polyline returned from
+// GetMedoidPolyline() is guaranteed to match an input polyline point-for-point.
+// NOTE: the number of points in our returned consensus polyline is always equal
+// to the number of points in the initial seed, which is implementation-defined.
+// If the collection of polylines has a large resolution distribution, it might
+// be a good idea to reinterpolate them to have about the same number of points.
+// In practice, this doesn't seem to matter, but is probably worth noting.
+//
+// ASYMPTOTIC BEHAVIOR:
+// Seeding this algorithm requires O(1) vertex alignments if seed_medoid =
+// false, and O(N^2) vertex alignments if seed_medoid = true. Once the seed
+// polyline is chosen, computing the consensus polyline requires at most
+// (iteration_cap)*N vertex alignments. For polylines of length U, V, the
+// alignment cost function evaluation is O(U+V) if options.approx = true, and
+// O(U*V) if options.approx = false.
+
+class ConsensusOptions {
+ public:
+  // If options.approx = false, vertex alignments are computed with
+  // GetExactVertexAlignment. If options.approx = true, vertex alignments are
+  // computed with GetApproxVertexAlignment, called with default radius
+  // parameter.
+  bool approx() const { return approx_; }
+  void set_approx(bool approx) { approx_ = approx; }
+
+  // If options.seed_medoid = true, we seed the consensus polyline with the
+  // medoid of the collection. This is a more expensive approach, but may result
+  // in higher quality consensus sequences by avoiding bad arbitrary initial
+  // seeds. Seeding with the medoid will incur up to (N^2 - N) / 2 evaluations
+  // of the vertex alignment function. If options.seed_medoid = false, we seed
+  // the consensus polyline by taking an arbitrary element from the collection.
+  bool seed_medoid() const { return seed_medoid_; }
+  void set_seed_medoid(bool seed_medoid) { seed_medoid_ = seed_medoid; }
+
+  // options.iteration_cap controls the maximum number of DBA refining steps we
+  // apply to the initial seed.
+  int iteration_cap() const { return iteration_cap_; }
+  void set_iteration_cap(int iteration_cap) { iteration_cap_ = iteration_cap; }
+
+ private:
+  bool approx_ = true;
+  bool seed_medoid_ = false;
+  int iteration_cap_ = 5;
+};
+
+std::unique_ptr<S2Polyline> GetConsensusPolyline(
+    const std::vector<std::unique_ptr<S2Polyline>>& polylines,
+    const ConsensusOptions options);
+}  // namespace s2polyline_alignment
+#endif  // S2_S2POLYLINE_ALIGNMENT_H_