mlpost 0.9 · OCaml Package

Fixed Paths

Paths are the objects used to describe lines, curves, and more generally almost everything that is drawn with Mlpost

type direction

A direction is used to put constraints on paths:

vec p defines a direction by a point (interpreted as a vector)
curl f changes the curling factor of the extremity of a path; higher curling factor means flatter curves
noDir means no particular direction

val vec : Point.t -> direction

val curl : float -> direction

val noDir : direction

type knot

A knot is the basic element of a path, and is simply a point with an incoming and outgoing direction constraint

val knotp : ?l:direction -> ?r:direction -> Point.t -> knot

Build a knot from a point; the optional arguments are the incoming directions. Warning they are going in the same direction.

val knotlist : (direction * Point.t * direction) list -> knot list

type joint

A joint is the connection between two knots in a path. It is either

jLine for a straight line
jCurve for a spline curve
jCurveNoInflex to avoid inflexion points
jTension f1 f2 to specify "tension" on the joint; jCurve uses a default tension of 1. Higher tension means less "wild" curves
jControls p1 p2 to explicitely specify control points

val jLine : joint

val jCurve : joint

val jCurveNoInflex : joint

val jTension : float -> float -> joint

val jControls : Point.t -> Point.t -> joint

type t

The abstract type of paths

In all the functions below :

noDir is the default direction
jCurve is the default joint

Labelled path constructors

val knot : 
  ?l:direction ->
  ?r:direction ->
  ?scale:(float -> Num.t) ->
  (float * float) ->
  knot

Build a knot from a pair of floats

parameter l
an incoming direction

parameter r
an outgoing direction

parameter scale
a scaling factor applied to the floats

val knotn : ?l:direction -> ?r:direction -> (Num.t * Num.t) -> knot

Build a knot from a Num.t pair; the optional arguments are as in knot

val path : 
  ?style:joint ->
  ?cycle:joint ->
  ?scale:(float -> Num.t) ->
  (float * float) list ->
  t

Build a path from a list of pairs of floats

parameter style
the joint style used for all joints in the path

parameter cycle
if given, the path is closed using the given style

parameter scale
permits to scale the whole path

val pathn : ?style:joint -> ?cycle:joint -> (Num.t * Num.t) list -> t

Same as path, but uses a Num.t list

val pathk : ?style:joint -> ?cycle:joint -> knot list -> t

Same as path, but uses a knot list

val pathp : ?style:joint -> ?cycle:joint -> Point.t list -> t

Same as path but uses a point list

val jointpathk : knot list -> joint list -> t

Build a path from n knots and n-1 joints

val jointpathp : Point.t list -> joint list -> t

Build a path from n points and n-1 joints, with default directions

val jointpathn : (Num.t * Num.t) list -> joint list -> t

val jointpath : 
  ?scale:(float -> Num.t) ->
  (float * float) list ->
  joint list ->
  t

Build a path from n float_pairs and n-1 joints, with default directions

val cycle : ?dir:direction -> ?style:joint -> t -> t

Close a path using direction dir and style style

Primitive path constructors

val concat : ?style:joint -> t -> knot -> t

Add a knot at the end of a path

val start : knot -> t

Create a simple path with one knot

val append : ?style:joint -> t -> t -> t

Append a path to another using joint style

More complex constructions on paths

val length : t -> Num.t

Number of nodes in a path, minus one.

val point : float -> t -> Point.t

point f p returns a certain point on the path p; f is given "in control points": 0. means the first control point, 1. the second and so on; intermediate values are accepted.

val pointn : Num.t -> t -> Point.t

Same as point but for a Num.t.

val direction : float -> t -> Point.t

direction f p returns the direction of the tangent at point f p.

val directionn : Num.t -> t -> Point.t

Same as direction but for a Num.t.

val subpath : float -> float -> t -> t

subpath start end path selects the subpath of path that lies between start and end. start and end are given in control points, as in point.

val subpathn : Num.t -> Num.t -> t -> t

Same as subpathn but using Num.t.

val transform : Transform.t -> t -> t

Apply a transformation to a path

val scale : Num.t -> t -> t

val rotate : float -> t -> t

val shift : Point.t -> t -> t

val yscale : Num.t -> t -> t

val xscale : Num.t -> t -> t

Shortcuts for transformations of Paths

val cut_after : t -> t -> t

cut_after p1 p2 cuts p2 after the intersection with p1. To memorize the order of the arguments, you can read: "cut after p1"

val cut_before : t -> t -> t

Same as cut_after, but cuts before

val strip : Num.t -> t -> t

strip n p removes two segments of length n at each end of path p

val build_cycle : t list -> t

Build a cycle from a set of intersecting paths

Predefined values

val defaultjoint : joint

The default joint style (JCurve)

val fullcircle : t

A full circle of radius 1 and centered on the origin

val halfcircle : t

The upper half of fullcircle

val quartercircle : t

The right half of halfcircle

val unitsquare : t

A full square of size 1 and centered on the origin

Conversions

type metapath = MetaPath.t

Compute the control point of the path for a good looking result according to the constraint on the direction, tension, curve

val of_metapath : metapath -> t

Compute the control point of the path for a good looking result according to the constraint on the direction, tension, curve

val to_metapath : t -> metapath

Obtain a metapath from a path with exactly the same control point. p = of_metapath (of_path p) is true but not the opposite.

Smart path

type orientation =

| Up
| Down
| Left
| Right
| Upn of Num.t
| Downn of Num.t
| Leftn of Num.t
| Rightn of Num.t

val smart_path : ?style:joint -> orientation list -> Point.t -> Point.t -> t

val draw : 
  ?brush:Brush.t ->
  ?color:Color.t ->
  ?pen:Pen.t ->
  ?dashed:Dash.t ->
  t ->
  Command.t

Draw a path

parameter brush
the brush used to draw the path; the next argument redefined this one

parameter color
the color of the path; default is black

parameter pen
the pen used to draw the path; default is Brush.Pen.default

parameter dashed
if given, the path is drawn using that dash_style.

val fill : ?color:Color.t -> t -> Command.t

Fill a contour given by a closed path

parameter color
the color used to fill the area; default is black