bergsoe avatar bergsoe committed 97daba4

API doc.

Comments (0)

Files changed (11)

     PaplSampler
     PaplStopCriteria
     PaplSubdivision
+    PaplTrajectory
 }
 
 {3 Planners}
     PaplSpatialGroup
     PaplSBLExpand
     PaplTransform
-    PaplTrajectory
     PaplTime
     PaplVector
     PaplVectorMetric

src/PaplMetric.mli

 *)
 
 val path_length : 'a t -> 'a list -> float
-(**
-   The length of a path.
+(** The length of a path.
+
+    The length [path_length dist path] is equal to the sum of the distances
+    between adjacent elements of [path]. The distances are computed by [dist].
 
-   The length of an empty path or a one-element path is undefined and raises an
-   exception.
+    The length of an empty path or a one-element path is undefined and raises an
+    exception.
 *)
 
 (** {2 Float metrics} *)
 
 (** {2 Tuple metrics} *)
 
+(**
+   The tuple metrics apply a separate metric for each coordinate of the tuple.
+*)
 module Tuple2 : sig
   val dist1 : 'a t -> 'b t -> ('a * 'b) t
+  (** The Manhattan distance. *)
 
   val dist2 : 'a t -> 'b t -> ('a * 'b) t
+  (** The Euclidean distance. *)
 
   val dist2_sqr : 'a t -> 'b t -> ('a * 'b) t
+  (** The square of Euclidean distance. *)
 
   val dist_inf : 'a t -> 'b t -> ('a * 'b) t
+  (** The max distance. *)
 end
 
 module type OPTION = sig
     coordinate using [ip].
 *)
 
+(** {2 Integer pairs} *)
 module Int : sig
   type t = int pair_t
 
     and type weight_t = float pair_t
 end
 
-(** {2 Metrics} *)
-
-(*
-module Metric : sig
-  module Int : PaplVectorMetric.S
-    with
-      type t = int pair_t
-    and
-      type weight_t = float pair_t
-
-  module Float : PaplVectorMetric.S
-    with
-      type t = float pair_t
-    and
-      type weight_t = float pair_t
-end
-*)
-
 (** {2 Planner constraints} *)
 
 module PlannerConstraint : sig

src/PaplPlannerConstraint.mli

 (** {2 Constructors} *)
 
 val fixed_reject : bool -> bool -> 'a t
+(** If [(nc, ec) = fixed_reject nr er] then [PaplConstraint.reject nc x == nr] and
+    [PaplConstraint.reject ec x == er] for all [x].
+*)
 
 val fixed_accept : bool -> bool -> 'a t
+(** If [(nc, ec) = fixed_reject na ea] then [PaplConstraint.accept nc x == na] and
+    [PaplConstraint.accept ec x == ea] for all [x].
+*)
 
 val constrain_by_subdivision :
   'a PaplConstraint.t ->
   'a PaplInterpolate.t ->
   'a PaplMetric.threshold_t ->
   'a t
+(** A planner constraint with a subdividing edge constraint.
+
+    See {! PaplEdgeConstraint.constrain_by_subdivision} for details.
+*)
 
 (** {2 Conversions} *)
 
 
 include module type of PaplVector.Array
 
-(* type box_t = t * t *)
-
 (** {2 Imperative operators} *)
 
 val ( *=:) : t -> float -> unit
 (** {2 Metrics} *)
 
 val dist_inf_box_normalized : box_t -> t PaplMetric.t
+(** The metric [dist= dist_inf_box_normalized (a, b)] is the weighted infinity
+    metric for which [dist a b == 1] (approximately).
+*)
 
 val dist2_box_normalized : box_t -> t PaplMetric.t
+(** The metric [dist= dist_inf_box_normalized (a, b)] is the weighted Euclidean
+    metric for which [dist a b == 1] (approximately).
+*)
 
 val dist2_sqr_box_normalized : box_t -> t PaplMetric.t
+(** The metric [dist= dist_inf_box_normalized (a, b)] is the square of the
+    weighted Euclidean metric for which [dist a b == 1] (approximately).
+*)
 
 (** {2 Boxes} *)
 
 *)
 
   val is_empty : box_t -> bool
+(** A box [(a, b)] is empty if [ai > bi] for any coordinate [i].
+*)
 end
 
 (** {2 Gram-Schmidt orthonormalization} *)

src/PaplSampler.mli

 (** Constraining the elements of a sampler.
 
     The sampler [constrain s c] returns [Some x] for every [x] of [s] that is
-    accepted by [c] and [None] otherwise.
+    accepted by [c] and [None] for those that are not.
 *)
 
 val constrain_with_default : 'a t -> 'a PaplConstraint.t -> 'a t -> 'a t

src/PaplSpatialGroup.mli

   *)
 
   type vec
-  (** The type a vector. *)
+  (** The type of a vector. *)
 
   val interpolate : t PaplInterpolate.t
   (** Interpolation between transformations. *)

src/PaplTrajectory.mli

 *)
 (** Trajectories
 
-    A {b trajectory} is a mapping from a range of real values [(t0, t1)] onto
-    some other values.
+    A {b trajectory} is a mapping on a range of real values [(t0, t1)] onto
+    values of some type.
 *)
 
 (** {2 Types} *)
 
 type 'a t
-(** The type of a trajectory. *)
+(** The type of a trajectory.
+
+    A trajectory of type [x_t t] maps a range of real values onto values of type
+    [x_t].
+*)
 
 type range_t = float * float
 (** The range of a trajectory.
 (** {2 Constructors} *)
 
 val empty : unit -> 'a t
-(** An empty trajectory. *)
+(** An empty trajectory.
+
+    The empty trajectory has an empty range, i.e. a range [(t0, t1)] for which
+    [t1 < t0].
+*)
 
 val make : range_t -> (float -> 'a) -> 'a t
 (** Construct a trajectory.
 
-    [make (t0, t1) get] constructs a trajectory with duration [(x0, x1)]. Values
-    for [t] in the range are extracted with [get t].
+    [make (t0, t1) get] constructs a trajectory on the range [(t0, t1)]. The
+    value of the trajectory at [t] is [get t].
 *)
 
 val make_fixed : range_t -> 'a -> 'a t
     [range].
 *)
 
-val of_interpolate :
-  range_t -> (float -> 'a) -> 'a t
-(** [of_interpolate (t0, t1) ip].
+val of_interpolate : range_t -> (float -> 'a) -> 'a t
+(** Construct a trajectory from an interpolation function.
 
-    [ip] is a function on the range [(0., 1.)].
+    The trajectory [of_interpolate (t0, t1) ip] takes a function [ip] on the
+    range [(0., 1.)] and scales this range to [(t0, t1)].
 
-    [(t0, t1)] is the resulting range.
+    For example, if [interpolate] is a planning space interpolation function
+    satisfying the requirements of {! PaplInterpolate} then [of_interpolate (t0,
+    t1) (interpolate x0 x1)] is trajectory that moves from [x0] to [x1] as time
+    moves from [t0] to [t1].
 *)
 
 val of_metric :
   'a PaplMetric.t ->
   'a -> 'a -> 'a t
 (** [of_metric ~t0 interpolate metric a b] constructs a trajectory on the range
-    [(~t0, t0 +. len)] that interpolates from [a] to [b] using [interpolate].
-    The duration [len] of the trajectory is the distance from [a] to [b]
-    measured by [metric].
+    [(t0, t0 +. len)] that interpolates from [a] to [b] using [interpolate]. The
+    duration [len] of the trajectory is the distance from [a] to [b] measured by
+    [metric].
+
+    If [t0] is omitted, then [t0] is set to [0.0].
 *)
 
 val of_list : ?t0:float -> 'a t list -> 'a t
     [interpolate]. The duration of that segment of the trajectory is
     equal to [metric x(i) x(i + 1)].
 
-    The starting time of the trajectory is [~t0] - or [0.0] if the [~t0]
-    argument is omitted.
+    The starting time of the trajectory is [t0] - or [0.] if the [t0] argument
+    is omitted.
 
     If the path length measured by [metric] is zero, the result is a fixed
     trajectory containing the value [xN].
 
     The starting time of the new trajectory is unchanged.
 
-    [s] must be greater than or equal to [0.].
+    [s] must be greater than or equal to [0.0].
 
     If [s = 0.] then a fixed trajectory containing the last element of
     [trajectory] is returned.
     [scale_to trajectory d] is equivalent to [scale trajectory (d /. duration
     trajectory)].
 
-    The duration of [trajectory] must be greater than or equal to [0.].
+    The duration of [trajectory] must be greater than or equal to [0.0].
 
     If the duration of [trajectory] is [0.] then a fixed trajectory containing
     the last element of [trajectory] is returned.
 
     If the duration of [traj] is [0.] then then a fixed trajectory containing
     the last element of [traj] is returned.
+
+    If [traj] is empty, an exception is thrown.
 *)
 
 val repeat_n : int -> 'a t -> 'a t
     The trajectories all end with [x1 traj]. Thus [repeat_n 0 traj] is
     equivalent to [make_fixed (t0, t0) (x1 traj)].
 
-    [traj] must have a duration greater than zero or an exception is thrown.
+    If [traj] is empty an exception is thrown.
 
-    [n] must be non-negative or an exception is thrown.
+    If [n] is negative an exception is thrown.
 *)
 
 val rev : 'a t -> 'a t
 
 module Tuple2 : sig
   val combine : 'a t * 'b t -> ('a * 'b) t
+  (** Combine a tuple of trajectories into a trajectory of tuples.
+
+      The range of the trajectory is equal to the intersection of the ranges of
+      the individual trajectories.
+  *)
 end
 
 module Tuple3 : sig
   val combine : 'a t * 'b t * 'c t -> ('a * 'b * 'c) t
+  (** Combine a tuple of trajectories into a trajectory of tuples.
+
+      The range of the trajectory is equal to the intersection of the ranges of
+      the individual trajectories.
+  *)
 end
 
 (** {2 Arrays} *)
 
 module Array : sig
   val combine : 'a t array -> 'a array t
-(**
-   The range of the resulting trajectory is equal to the intersection of the
-   ranges.
+(** Combine an array of trajectories into a trajectory of arrays.
+
+    The range of the resulting trajectory is equal to the intersection of the
+    ranges of the individual trajectories.
 *)
 end

src/PaplTransform.mli

         from the angle [a] to the angle [b].
     *)
 
+  (** Sampling of rotations *)
   module Sampler : sig
     val uniform : ?rng:rng_t -> (float * float) -> t PaplSampler.t
       (** Uniform sampling over a range of angles.
         [dist a b] is equivalent to [angle (mul (inverse a) b)].
     *)
 
+  (** Sampling of rotations *)
   module Sampler : sig
     val uniform_all : ?rng:rng_t -> unit -> t PaplSampler.t
     (** Uniformly distributed random rotations.
 (** Interface common to SE2 and SE3. *)
 module type SE = sig
   type t
+  (** Transformation type. *)
+
   type vec
+  (** Vector type. *)
+
   type rot
+  (** Rotation type. *)
 
   include PaplSpatialGroup.S with type t := t and type vec := vec
   include SE_METRIC with type t := t
 
   val make : vec -> rot -> t
+  (** Construct a transformation from a translation and a rotation. *)
+
   val make_rotate : rot -> t
+  (** Construct a transformation with a given rotation and a translation of
+      zero. *)
+
   val make_translate : vec -> t
+  (** Construct a transformation with a given translation and a rotation of
+      zero. *)
 
   val rotation : t -> rot
+  (** The rotation component of a transformation. *)
+
   val translation : t -> vec
+  (** The translation component of a transformation. *)
+
   val get : t -> vec * rot
+  (** The translation and rotation components of a transformation. *)
 end
 
 (** 2D transformations *)
   include SE with type vec = SO2.vec and type rot = SO2.t
 
   val make_pos_angle : vec -> float -> t
+  (** Construct a transformation from a translation and an angle of rotation. *)
+
   val make_angle : float -> t
+  (** Construct a transformation an angle of rotation. The translation of the
+      transformation is set to zero. *)
 
   val pos_angle : t -> vec * float
+  (** The translation vector and angle of rotation of a transformation. *)
+
   val pos_complex : t -> vec * Complex.t
+  (** The translation vector and the rotation of a transformation - the rotation
+      is represented by a complex number [{ re = cos v; im = sin v }] where [v]
+      is the angle of rotation. *)
 
+  (** Sampling of transformations *)
   module Sampler : sig
     type box_t = vec * vec
+    (** A box of positions. *)
 
     val make : vec PaplSampler.t -> SO2.t PaplSampler.t -> t PaplSampler.t
+    (** Construct a sampler of transformation from a sampler of translations and
+        a sampler of rotations.
+
+        If either of the samplers become empty, the sampler of
+        transformations is empty too.
+    *)
 
     val uniform : ?rng:rng_t -> box_t -> (float * float) -> t PaplSampler.t
+    (** Uniform sampling of a box positions and a range of angles.
+    *)
 
     val uniform_all : ?rng:rng_t -> box_t -> t PaplSampler.t
+    (** Uniform sampling of a box of positions and the full set of all possible
+        rotations. *)
   end
 end
 
 module SE3 : sig
   include SE with type vec = SO3.vec and type rot = SO3.t
 
+  (** Sampling of transformations *)
   module Sampler : sig
     type box_t = vec * vec
+    (** A box of positions. *)
 
     val make : vec PaplSampler.t -> SO3.t PaplSampler.t -> t PaplSampler.t
+    (** Construct a sampler of transformation from a sampler of translations and
+        a sampler of rotations.
+
+        If either of the samplers become empty, the sampler of
+        transformations is empty too.
+    *)
 
     val uniform_offset : ?rng:rng_t -> box_t -> float -> t PaplSampler.t
     (** [uniform_offset box angle_offset] are random transformations with
           r21; r22; r23; py;
           r31; r32; r33; pz |\]]
 
-      where the [r] is the rotation matrix representation of the orientation
+      where the [rij] is the rotation matrix representation of the orientation
       and [(px, py, pz)] is the translation vector.
   *)
 end

src/PaplVector.mli

 (** Basic vector operations *)
 module type BASE = sig
   type t
-(** A vector configuration. *)
+(** Vectors. *)
 
   type box_t = t * t
+(** Vector boxes. *)
 
 (** {2 Interpolation} *)
 
 (** Map a function onto the elements of a vector. *)
 
   val map2 : (float -> float -> float) -> t -> t -> t
+(** Zip the pairs of coordinates of two vectors by a scalar function. *)
 
   val sum : t -> float
 (** The sum of the elements. *)
 (** Inner products *)
 module type DOT = sig
   type t
+(** Vectors. *)
 
 (** {2 Inner products} *)
 
 
 (** Sampling of vectors *)
 module type SAMPLER = sig
-
   type t
+(** Vectors. *)
+
   type box_t
+(** Vector boxes. *)
 
   val uniform : ?rng:rng_t -> box_t -> t PaplSampler.t
 (** Uniform sampling of a configuration space box. *)

src/PaplVectorMetric.mli

 (** Vector metric signature *)
 module type S = sig
   type t
+(** Vectors. *)
+
   type weight_t
+(** Weights for the scaling of vectors. 
+
+    The weight type is often but not always a vector of type [t] itself.
+*)
 
 (** {2 Metrics} *)
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.