#define POLYID_NONE
#define POLYID_UNKNOWN
-\fP
-.fi
-.SH FUNCTIONS
-
-.nf
-\f5
int Pshortestpath(Ppoly_t *boundary, Ppoint_t endpoints[2], Ppolyline_t *output_route);
-\fP
-.fi
-Finds a shortest path between two points in a simple polygon.
-You pass endpoints interior to the polygon boundary.
-A shortest path connecting the points that remains in the polygon
-is returned in output_route. If either endpoint does not lie in
-the polygon, an error code is returned. (what code!!)
-.nf
-\f5
vconfig_t *Pobsopen(Ppoly_t **obstacles, int n_obstacles);
-.br
int Pobspath(vconfig_t *config, Ppoint_t p0, int poly0, Ppoint_t p1, int poly1, Ppolyline_t *output_route);
-.br
void Pobsclose(vconfig_t *config);
+
+int Proutespline (Pedge_t *barriers, int n_barriers, Ppolyline_t input_route, Pvector_t endpoint_slopes[2],
+ Ppolyline_t *output_route);
+
+int Ppolybarriers(Ppoly_t **polys, int n_polys, Pedge_t **barriers, int *n_barriers);
\fP
.fi
-These functions find a shortest path between two points in a
-simple polygon that possibly contains polygonal obstacles (holes).
-\f5Pobsopen\fP creates a configuration (an opaque struct of type
-\f5vconfig_t\fP) on a set of obstacles. \f5Pobspath\fP finds
+.SH DESCRIPTION
+\fBlibpathplan\fR provides functions for creating spline paths in the plane that
+are constrained by a polygonal boundary or obstacles to avoid.
+All polygons must be simple, but need not be convex.
+.P
+.SS " int Pshortestpath(Ppoly_t *boundary, Ppoint_t endpoints[2], Ppolyline_t *output_route);"
+The function \fIPshortestpath\fP
+finds a shortest path between two points in a simple polygon.
+The polygon is specified by a list of its vertices,
+in either clockwise or counterclockwise order.
+You pass endpoints interior to the polygon boundary.
+A shortest path connecting the points that remains in the polygon
+is returned in \fIoutput_route\fP. If either endpoint does not lie in
+the polygon, -1 is returned; otherwise, 0 is returned on success.
+The array of points in \fIoutput_route\fP is static to the library. It should
+not be freed, and should be used before another call to \fIPshortestpath\fP.
+.P
+.SS " vconfig_t *Pobsopen(Ppoly_t **obstacles, int n_obstacles);"
+.SS " Pobspath(vconfig_t *config, Ppoint_t p0, int poly0, Ppoint_t p1, int poly1, Ppolyline_t *output_route);"
+.SS " void Pobsclose(vconfig_t *config);"
+.P
+These functions find a shortest path between two points in the plane
+that contains polygonal obstacles (holes).
+\fIPobsopen\fP creates a configuration (an opaque struct of type
+\f5vconfig_t\fP) on a set of obstacles.
+The \fIn_obstacles\fP obstacles are given in the array \fIobstacles\fP;
+the points of each polygon should be in clockwise order.
+The function \fIPobsclose\fP frees the data allocated in \fIPobsopen\fP.
+.P
+\f5Pobspath\fP finds
a shortest path between the endpoints that remains outside the
obstacles. If the endpoints are known to lie inside obstacles,
\f5poly0\fP or \f5poly1\fP should be set to the index in the
\f5obstacles\fP array. If an endpoint is definitely not inside
an obstacle, then \f5POLYID_NONE\fP should be passed. If the
caller has not checked, then \f5POLYID_UNKNOWN\fP should be passed,
-and the path library will perform the test.
-
-(!! there is no boundary polygon in this model?!!!)
-
-.nf
-\f5
-int Proutespline (Pedge_t *barriers, int n_barriers, Ppolyline_t input_route, Pvector_t endpoint_slopes[2],
- Ppolyline_t *output_route);
-\fP
-.fi
-
-This function fits a Bezier curve to a polyline path.
-The curve must avoid a set of barrier segments. The polyline
+and the path library will perform the test. The resulting shortest path
+is returned in \fIoutput_route\fP. Note that this function does not provide
+for a boundary polygon. The array of points stored in \fIoutput_route\fP are
+allocated by the library, but should be freed by the user.
+.P
+.SS " int Proutespline (Pedge_t *barriers, int n_barriers, Ppolyline_t input_route, Pvector_t endpoint_slopes[2], Ppolyline_t *output_route);"
+This function fits a cubic B-spline curve to a polyline path.
+The curve is constructed to avoid a set of \fIn_barriers\fP barrier line segments
+specified in the array \fIbarriers\fP. If you start with polygonal obstacles, you
+can supply each polygon's edges as part of the barrier list.
+The polyline \f5input_route\fP provides a template for the final path; it
is usually the \f5output_route\fP of one of the shortest path
finders, but it can be any simple path that doesn't cross
-any obstacles. The input also includes endpoint slopes and
-0,0 means unconstrained slope.
-
-Finally, this utility function converts an input list of polygons
-into an output list of barrier segments:
-.nf
-\f5
-int Ppolybarriers(Ppoly_t **polys, int n_polys, Pedge_t **barriers, int *n_barriers);
-\fP
-.fi
-
+any barrier segment. The input also allows the specification of desired
+slopes at the endpoints via \fIendpoint_slopes\fP. These are specified as vectors.
+For example, to have an angle of \fIT\fP at an endpoing, one could use
+\fI(cos(T),sin(T))\fP.
+A vector (0,0) means unconstrained slope.
+The output is returned in \fIoutput_route\fP and consists of the control points
+of the B-spline. The function return 0 on success; a return value of -1 indicates
+failure.
+The array of points in \fIoutput_route\fP is static to the library. It should
+not be freed, and should be used before another call to \fIProutespline\fP.
+.P
+.SS " int Ppolybarriers(Ppoly_t **polys, int n_polys, Pedge_t **barriers, int *n_barriers);"
+This is a utility function that converts an input list of polygons
+into an output list of barrier segments.
+The array of points in \fIbarriers\fP is static to the library. It should
+not be freed, and should be used before another call to \fIPpolybarriers\fP.
+The function returns 1 on success.
+.SH BUGS
+The function \fIProutespline\fP does not guarantee that it will preserve the
+topology of the input path as regards the boundaries. For example, if
+some of the segments correspond to a small polygon, it may be possible that the
+final path has flipped over the obstacle.
.SH AUTHORS
David Dobkin (dpd@cs.princeton.edu),
Eleftherios Koutsofios (ek@research.att.com),
projects / graphviz / commitdiff