Source

papl_robwork / src / PaplRobwork.mli

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

(** {2 Types} *)

type workcell_t
(** Workcells. *)

type state_t
(** States. *)

type device_t
(** Devices. *)

type frame_t
(** Frames. *)

type fk_t
(** Forward kinematics lookup table. *)

type transform_t = float array
(** 3D rigid body transformations.

    The array is 12 elements long and contains the rows of a 3x4 transformation
    matrix. More precisely stated, if the rotation matrix is [R = (rij)] and the
    translation vector is [p = (px, py, pz)], then the array for the
    transformation is equal to [ \[| r00; r01; r02; px; r10; r11; r12; py; r20;
    r21; r22; pz |\] ].
*)

type q_t = float array
(** Configurations. *)

type time_state_t = state_t PaplTime.t
(** Time-stamped states. *)

exception Exception of string
(** The type of exception used by this module.

    The exception contains an error message.
*)

(** {2 Operations} *)

(** {3 Workcells} *)

val load_workcell : string -> workcell_t
(** Load a workcell from a file.

    An exception is thrown if the workcell can't be loaded.
*)

val get_state : workcell_t -> state_t
(** [get_state workcell] is a copy of the initial workcell state.
*)

val get_device : workcell_t -> string -> device_t
(** [get_device workcell name] is the device in [workcell] named [name].

    An exception is thrown if a device with this name doesn't exist.
*)

val get_frame : workcell_t -> string -> frame_t
(** [get_frame workcell name] is the frame in [workcell] named [name].

    An exception is thrown if a frame with this name doesn't exist.
*)

val get_world_frame : workcell_t -> frame_t
(** The world frame of the workcell. *)

(** {3 Devices and states} *)

val get_dof : device_t -> int
(** The number of degrees of freedom of a device.

    The {i dof} of a device is equal to the length of its configurations.
*)

val get_end : device_t -> frame_t
(** The end-effector of the device. *)

val get_bounds : device_t -> q_t * q_t
(** The configuration space box for the device.
*)

val get_velocity_limits : device_t -> q_t
(** The maximum velocities for the joint values of a device. *)

val set_q : state_t -> device_t -> q_t -> unit
(** Set a configuration for a device.

    [set_q state device q] writes the configuration [q] for [device] to [state].

    If the dimensions of [device] and [q] do not match, an exception is thrown.
*)

val get_q : state_t -> device_t -> q_t
(** The configuration of a device.

    [q = get_q state device] is the configuration of [device] in the state [state].
*)

val copy_state : state_t -> state_t
(** A copy of a state. *)

val update_q : state_t -> device_t -> q_t -> state_t
(** [update_q state device q] returns a copy of [state] with the configuration
    for [device] set to [q].
*)

(** {3 Frames} *)

val grip_frame : frame_t -> frame_t -> state_t -> unit
(** [grip_frame item gripper state] attachs [item] to [gripper] in [state], such
    that the current world transformation of [item] is unchanged.

    The item must be a DAF (so that it can be attached to [gripper]) and it must
    of type Movable (so that its local transformation can be changed). Otherwise
    an exception is thrown.
*)

(** {3 Collision detection} *)

val in_collision : workcell_t -> state_t -> bool
(** Collision detection for a workcell.

    [in_collision workcell state] is [true] if the workcell is in collision in
    state [state].
*)

(** {3 Data export} *)

val write_time_state_path : workcell_t -> time_state_t list -> string -> unit
(** Write a path of time-stamped states to a file.

    The file can be loaded into RobWorkStudio by its PlayBack plugin.
*)

(** {2 Forward kinematics} *)

module FK : sig
  val make : state_t -> fk_t
  (** Forward kinematics table for a state.
  *)

  val get : fk_t -> frame_t -> transform_t
  (** [get fk frame] is the transformation of [frame] in the world
      frame given the state [fk].
  *)
end

(** {2 Trajectories} *)

module Trajectory : sig
  val of_device_trajectories :
    state_t ->
    (device_t * q_t PaplTrajectory.t) list ->
    state_t PaplTrajectory.t
end

(** {2 Constraints} *)

module Constraint : sig
  val state_in_collision :
    workcell_t -> state_t PaplConstraint.t
(** Collision detection constraint for the state of a workcell.

    The constraint [state_in_collision workcell] rejects a state [state] if
    [in_collision workcell state] is [true].
*)

  val q_in_collision :
    ?state:state_t ->
    workcell_t ->
    device_t ->
    q_t PaplConstraint.t
(** Collision detection constraint for the configurations of a device.

    The constraint [q_in_collision state workcell device] rejects configurations
    [q] for [device] for which [workcell] is in collision when the configuration
    of device in [state] is set to [q].

    The constraint does not modify the [state] parameter.

    If no [state] is given then [get_state workcell] is used.
*)

  val q_time_in_collision :
    ?state:state_t ->
    workcell_t ->
    (device_t * q_t PaplTrajectory.t) list ->
    device_t ->
    q_t PaplTime.t PaplConstraint.t
(** Collision detection constraint for a device in a known time dependent
    environment.

    The constraint [q_time_in_collision state workcell obstacles device] rejects
    configurations [qt] for [device] for which [state] of [workcell] is in
    collision at the configurations given by [qt] and [obstacles].

    If no [state] is given then [get_state workcell] is used.

    See also {! q_time}.
*)

  val q_time :
    state_t ->
    state_t PaplConstraint.t ->
    (device_t * q_t PaplTrajectory.t) list ->
    device_t ->
    q_t PaplTime.t PaplConstraint.t
(** Constraint for a device in a known time dependent environment.

    Given a time-stamped configuration [qt], the constraint [q_time state constr
    obstacles device] writes to [state] the obstacle configurations given by
    [obstacles] and the configuration [qt.q] for [device], and evaluates
    [constr] for the resulting state.

    The constraint does not modify the [state] parameter.
*)
end

(** {2 Metrics} *)

module Metric : sig
  val q_time_dist : device_t -> q_t PaplMetric.t
(** Time distance metric for the configurations of a device.

    The metric [dist = q_time_dist device] is a scaled infinity norm. The metric
    assumes that the joints of [device] are capable of moving with the maximum
    velocities given by {! get_velocity_limits}.
*)

  val state_time_dist : device_t -> state_t PaplMetric.t
(** Time distance metric for the configurations of a device.

    The device configurations are extracted from states of the workcell.

    The time distance is computed as explained for {! q_time_dist}.
*)
end

(** {2 Utilities} *)

val to_state_path :
  state_t -> device_t -> q_t list -> state_t list
(** [to_state_path state device qs] converts a path of configurations [qs] for
    the device [device] and the state [state] to the corresponding path of
    states.

    The function does not modify the [state] parameter.
*)

val to_time_state_path :
  state_t -> device_t -> q_t PaplTime.t list -> state_t PaplTime.t list
(** [to_time_state_path state device qts] converts a path of time-stamped
    configurations [qts] for the device [device] and the state [state] to the
    corresponding path of time-stamped states.

    The function does not modify the [state] parameter.
*)