Module Vg.P

Paths.

Consult their semantics.

The |> operator is used to build paths from the empty path. For this reason path combinators always take the path to use as the last argument.

Path areas

type cap = [
  1. | `Butt
  2. | `Round
  3. | `Square
]

The type for path caps. Semantics.

type join = [
  1. | `Bevel
  2. | `Miter
  3. | `Round
]

The type for segment jointures. Semantics.

type dashes = float * float list

The type for dashes. Semantics.

type outline = {
  1. width : float;
    (*

    Outline width.

    *)
  2. cap : cap;
    (*

    Shape at the end points of open subpaths and dashes.

    *)
  3. join : join;
    (*

    Shape at segment jointures.

    *)
  4. miter_angle : float;
    (*

    Limit angle for miter joins (in [0;pi]).

    *)
  5. dashes : dashes option;
    (*

    Outline dashes.

    *)
}

The type for path outline area specifications. Semantics.

val o : outline

o holds a default set of values. width is 1., cap is `Butt, join is `Miter, miter_angle is 11.5 degrees in radians and dashes is None.

val pp_outline : Stdlib.Format.formatter -> outline -> unit

pp_outline ppf o prints a textual representation of o on ppf.

type area = [
  1. | `Aeo
  2. | `Anz
  3. | `O of outline
]

The type for path area specifications. Semantics.

val pp_area : Stdlib.Format.formatter -> area -> unit

pp_area ppf a prints a textual representation of a on ppf

Paths

type t = path

The type for paths.

val empty : path

empty is the empty path.

Subpaths and segments

If a path segment is directly added to a path p which is empty or whose last subpath is closed, a new subpath is automatically started with sub P2.o p.

In the functions below the default value of the optional argument rel is false. If true, the points given to the function are expressed relative to the last point of the path or Gg.P2.o if the path is empty.

val sub : ?rel:bool -> Gg.p2 -> path -> path

sub pt p is p with a new subpath starting at pt. If p's last subpath had no segment it is automatically closed.

val line : ?rel:bool -> Gg.p2 -> path -> path

line pt p is p with a straight line from p's last point to pt.

val qcurve : ?rel:bool -> Gg.p2 -> Gg.p2 -> path -> path

qcurve c pt p is p with a quadratic bézier curve from p's last point to pt with control point c.

val ccurve : ?rel:bool -> Gg.p2 -> Gg.p2 -> Gg.p2 -> path -> path

ccurve c c' pt p is p with a cubic bézier curve from p's last point to pt with control points c and c'.

val earc : ?rel:bool -> ?large:bool -> ?cw:bool -> ?angle:float -> Gg.size2 -> Gg.p2 -> path -> path

earc large cw a r pt p is p with an elliptical arc from p's last point to pt. The ellipse is defined by the horizontal and vertical radii r which are rotated by a with respect to the current coordinate system. If the parameters do not define a valid ellipse (points coincident or too far apart, zero radius) the arc collapses to a line.

In general the parameters define four possible arcs, thus large indicates if more than pi radians of the arc is to be traversed and cw if the arc is to be traversed in the clockwise direction (both default to false). In the following image, in red, the elliptical arc from the left point to the right one. The top row is ~large:false and the left column is ~cw:false:

val close : path -> path

close p is p with a straight line from p's last point to p's current subpath starting point, this ends the subpath.

Derived subpaths

The following convenience functions start and close a new subpath to the given path.

val circle : ?rel:bool -> Gg.p2 -> float -> path -> path

circle c r p is p with a circle subpath of center c and radius r.

val ellipse : ?rel:bool -> ?angle:float -> Gg.p2 -> Gg.size2 -> path -> path

ellipse c r p is p with an axis-aligned (unless angle is specified) ellipse subpath of center c and radii r.

val rect : ?rel:bool -> Gg.box2 -> path -> path

rect r p is p with an axis-aligned rectangle subpath r. If r is empty, p is returned.

val rrect : ?rel:bool -> Gg.box2 -> Gg.size2 -> path -> path

rrect r cr p is p with an axis-aligned rectangle subpath r with round corners of radii cr. If r is empty, p is returned.

val smooth_qcurve : ?rel:bool -> Gg.p2 -> path -> path

smooth_qcurve pt p is qcurve c pt p with control point c defined as the reflexion of the control point of the previous quadratic curve relative to the last point of p. If the previous segment of p is not a quadratic curve, c is the last point of p or the origin if the path is empty.

val smooth_ccurve : ?rel:bool -> Gg.p2 -> Gg.p2 -> path -> path

smooth_ccurve c' pt p is ccurve c c' pt p with control point c defined as the reflexion of the second control point of the previous cubic curve relative to the last point of p. If the previous segment of p is not a cubic curve, c is the last point of p or the origin if the path is empty.

Functions

val last_pt : path -> Gg.p2

last_pt p is the last point of p's last subpath. Raises Invalid_argument if p is empty.

val append : path -> path -> path

append p' p appends p' to p. If p's last subpath had no segment it is closed.

Warning. To accomodate |> the argument order is the opposite of List.append.

val tr : Gg.m3 -> path -> path

tr m p is the affine transform in homogenous 2D space of the path p by m.

Bug. Elliptical arcs transformation is currently broken if m doesn't scale uniformely or shears.

Traversal

type fold = [
  1. | `Sub of Gg.p2
    (*

    New subpath starting at point, the point

    *)
  2. | `Line of Gg.p2
    (*

    Line to point, the point

    *)
  3. | `Qcurve of Gg.p2 * Gg.p2
    (*

    Quadratic curve to point, a control point and the point

    *)
  4. | `Ccurve of Gg.p2 * Gg.p2 * Gg.p2
    (*

    Cubic curve to point, two control points and the point

    *)
  5. | `Earc of bool * bool * float * Gg.size2 * Gg.p2
    (*

    Elliptic arc to point, large, cw, angle, raddii and the point

    *)
  6. | `Close
    (*

    Line to point of the last `Sub, ends the subpath.

    *)
]

The type for path folds.

val fold : ?rev:bool -> ('a -> fold -> 'a) -> 'a -> path -> 'a

fold ~rev f acc p, applies f to each subpath and subpath segments with an accumulator. Subpaths are traversed in the order they were specified, always start with a `Sub, but may not be `Closed. If rev is true (defaults to false) the segments and subpaths are traversed in reverse order.

Predicates and comparisons

val is_empty : path -> bool

is_empty p is true iff p is empty.

val equal : path -> path -> bool

equal p p' is p = p'.

val equal_f : (float -> float -> bool) -> path -> path -> bool

equal_f eq p p' is like equal but uses eq to test floating point values.

val compare : path -> path -> int

compare p p' is Stdlib.compare p p'.

val compare_f : (float -> float -> int) -> path -> path -> int

compare_f cmp p p' is like compare but uses cmp to compare floating point values.

Formatters

val pp : Stdlib.Format.formatter -> path -> unit

pp ppf p prints a textual representation of p on ppf.

val pp_f : (Stdlib.Format.formatter -> float -> unit) -> Stdlib.Format.formatter -> path -> unit

pp_f pp_float ppf p prints p like pp but uses pp_float to print floating point values.

val to_string : path -> string
  • deprecated

    use pp instead.