Source

papl / src / PaplInterpolate.mli

Full commit
(*
  Copyright (c) 2012 Anders Lau Olsen.
  See LICENSE file for terms and conditions.
*)
(**
   Planning spaces

   A motion planner searches for a path in a planning space. The type of the
   planning space is user defined and depends on the robot and the planning
   problem. This library does not distinguish between configuration space and
   state space planning. A member of a planning space is called a {b
   configuration} regardless of the nature of the planning.

   Planning spaces may support a number of operations discussed in modules such
   as {! PaplMetric}, {! PaplSampler}, {! PaplConstraint}, and more. The {!
   PaplInterpolate} module is concerned with the property of being able to move
   between a pair of discrete configurations. This is called {b interpolation}
   and is accomplished by a function of type {! t}.
*)

(** {2 Types} *)

type 'a t = 'a -> 'a -> float -> 'a
(** Interpolation function for a planning space.

    An interpolation function [interpolate] called as [x = interpolate a b s]
    returns a configuration [x] on the movement connecting [a] to [b]. The
    interpolation parameter [s] must be in the range [\[0, 1\]].
*)

type 'a option_t = 'a -> 'a -> float -> 'a option
(** Optional interpolation for a planning space.

    An interpolation function [interpolate] of this type called as [interpolate
    a b s] returns [None] if a point [x] for the motion from [a] to [b] can't be
    found for the position [s]. Otherwise the function returns [Some x].

    The function may {e not} guarantee that if [interpolate a b s] succeeds (or
    fails) for some [s] then [interpolate a b s] will succeed (or fail) for {e
    all} [s].
*)

type 'a intermediary_t = 'a -> 'a -> 'a BatEnum.t
(** Splitting of a movement into intermediary configurations.

    A function [intermediary] called as [intermediary a b] returns a stream of
    configurations on the movement from [a] to [b]. Algorithms that use such
    functions generally expect [intermediary a b] not to include [a] and [b] in
    the stream.
*)

val intermediary_steps :
  'a t -> 'a PaplMetric.threshold_t -> 'a intermediary_t
(** If [im = intermediary_steps ip (metric, eps)] then [im a b] are the
    intermediary steps of length [eps] connecting [a] to [b].

    [a] and [b] are not explicitly included in the stream (but they can be if
    the interpolation function [ip] happens to return them).
*)

(** {2 Float planning space} *)

(** Planning space for floats.

    Floats are interpolated linearly.
*)
module Float : sig
  val interpolate : float t
end

(** {2 Int planning space} *)

(** Planning space for integers.

    The integers are interpolated linearly as if they were floats and then
    rounded to the nearest integer.
*)
module Int : sig
  val interpolate : int t
end

(** {2 Tuple planning spaces} *)

(** Planning spaces for tuples.

    Tuples coordinates can have separate types. Each coordinate is interpolated
    with its own interpolation function.
*)

module Tuple2 : sig
  val interpolate : 'a t -> 'b t -> ('a * 'b) t
end

module Tuple3 : sig
  val interpolate : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t
end

(** {2 List planning space} *)

(** Planning space for lists.

    Configurations are lists.

    Each coordinate is interpolated independently.

    Lists that are interpolated must have the same length; otherwise
    [Invalid_argument] is raised.
*)
module List : sig
  val interpolate : 'a t -> 'a list t
end

(** {2 Array planning space} *)

(** Planning space for arrays.

    Configurations are arrays.

    Each coordinate is interpolated independently.

    Arrays that are interpolated must have the same length; otherwise
    [Invalid_argument] is raised.
*)
module Array : sig
  val interpolate : 'a t -> 'a array t
end