Source

papl / src / PaplPlanner.mli

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

(** Motion planners *)

(** {2 Types} *)

(*
    A call [planner stop (from, to)] of a planner [planner] searches for a path
    connecting a start region [from] to a goal region [end]. The planner
    regularly calls [stop] to decide if the search should continue. The planner
    returns [None] either if [stop] says stop or the planner has decided or
    determined that it can't find a solution path.
*)

type 'a pair_t = 'a * 'a

type 'a region_t = 'a list PaplSampler.t

type 'a region_pair_t = 'a region_t pair_t

exception Path_not_found of string

(** {3 General planner types} *)

type ('target, 'result) t = PaplStopCriteria.t -> 'target -> 'result

type ('target, 'result) option_t = ('target, 'result option) t

(** {3 Path planner types} *)

type ('target, 'q) path_t = ('target, 'q list) t

type 'a point_path_t = ('a * 'a, 'a) path_t

type 'a region_path_t = ('a region_pair_t, 'a) path_t

(** {3 Trajectory planner types} *)

type ('target, 'q) trajectory_t = ('target, 'q PaplTrajectory.t) t

type 'q point_trajectory_t = ('q * 'q, 'q) trajectory_t

type 'a region_trajectory_t = ('a region_pair_t, 'a) trajectory_t

(** {2 General planner operations} *)

val fail : string -> 'a
(** [fail msg] raises [Path_not_found msg]. *)

val to_option : ('target, 'result) t -> ('target, 'result) option_t
(** [to_option planner] calls [planner] and returns [Some result] if the planner
    succesfully returns [result] and [None] if the planner throws a
    [Path_not_found] exception.
*)

val bind_target :
  ('target2 -> 'target1) ->
  ('target1, 'result) t ->
  ('target2, 'result) t

val map_result :
  ('result1 -> 'result2) ->
  ('target, 'result1) t ->
  ('target, 'result2) t

val region_to_point_planner :
  ('a region_t pair_t, 'result) t ->
  ('a pair_t, 'result) t

val point_to_region : 'a -> 'a region_t
(** Convert a point to a region containing that point and nothing else.
*)

val point_to_region_planner :
  ('a pair_t, 'result) t ->
  ('a region_t pair_t, 'result) t

(** {2 Trajectory planning} *)

module Trajectory : sig
  val of_metric :
    ?t0:float ->
    'a PaplInterpolate.t ->
    'a PaplMetric.t ->
    ('target, 'a) path_t ->
    ('target, 'a) trajectory_t
  (** Path planner to trajectory planner conversion.
  *)
end

(** {2 Path planner module types} *)

module type S = sig
  type q_t
  type target_t

  val planner : (target_t, q_t) path_t
end

module type POINT = sig
  type q_t
  include S with type q_t := q_t
            and type target_t = q_t * q_t
end

module type REGION = sig
  type q_t
  include S with type q_t := q_t
            and type target_t = q_t region_t pair_t
end

(** {2 Utilities} *)

val make_buffered_region :
  ?region_name : string ->
  ?max_region_tries : int ->
  ?max_constr_tries : int ->
  ?max_buffer_len : int ->
  ?retrieve : (int -> int -> bool) ->
  'q PaplConstraint.t ->
  'q region_t ->
  'q region_t
(** A buffered region that returns at most one configuration at a time.

    The region [buffer = make_buffered_region ~region_name ~max_region_tries
    ~max_constr_tries ~max_buffer_len ~retrieve constr region] maintains a
    buffer of configurations sampled from [region]. Only the configurations of
    [region] that are accepted by [constr] are added to the buffer.

    [region] is sampled each time that [buffer] is sampled, but only if the
    current number of elements in the buffer is less than [~max_buffer_len].

    If the buffer is non-empty and [~retrieve m n] returns [true] then [buffer]
    removes an element [q] from the buffer and returns the single-element list
    [\[q\]]. [m] is the number of times that [buffer] has been sampled and [n]
    is the number of times that a single-element list was returned (the
    remaining [m - n] times an empty list was returned).

    If [m > ~max_region_tries] and [region] has never returned a non-empty list,
    then [buffer] fails with an error message.

    If [constr] has been invoked more that [~max_constr_tries] and an acceptable
    configuration is yet to be found, then [buffer] fails with an error message.

    [~region_name] is used as the name of the region in error messages.
*)