Module Clipper.MakeD

MakeD (V) (C) creates a Clipper2 module with the 2d float vector V, and a user configuration (see config for convenience constructor). Same as MakeD', but the contour and polygon types is preset to use list.

Parameters

module V : V with type n := float
module _ : Config

Signature

type clip_type = [
  1. | `None
  2. | `Intersection
    (*

    AND -- regions covered by both subject and clip polygons

    *)
  3. | `Union
    (*

    OR -- regions covered by subject or clip polygons, or both polygons

    *)
  4. | `Difference
    (*

    NOT -- regions covered by subject, but not clip polygons

    *)
  5. | `Xor
    (*

    exclusive or -- regions covered by subject or clip polygons, but not both

    *)
]

Clipping types for boolean operations. See Clipper2's docs for visual demonstrations.

type fill_rule = [
  1. | `EvenOdd
    (*

    only odd numbered sub-regions are filled

    *)
  2. | `NonZero
    (*

    non-zero sub-regions are filled

    *)
  3. | `Positive
    (*

    only sub-regions with winding counts > 0 are filled

    *)
  4. | `Negative
    (*

    only sub-regions with winding counts < 0 are filled

    *)
]

Filling rules used by the clipping algorithm for boolean operations. See Clipper2's docs for a detailed explanation of how they differ).

type join_type = [
  1. | `Square
    (*

    squaring applied uniformally at all joins where the internal join angle is less than 90 degrees. The squared edg will be at exactly the offset distance from the join vertex

    *)
  2. | `Round
    (*

    rounding is appliedto all joins that have convex external angles, and it maintains the exact offset distance from the join vertex

    *)
  3. | `Miter
    (*

    there's a necessary limit to mitered joins (to avoid narrow angled joins producing excessively long and narrow spikes)). The limit sets the maximum distance in multiples of the delta specified for the offsetting operation (default is 2., which is the minimum allowed).

    *)
]

Defines the treatment of corners when offsetting paths. Visual examples are available in the Clipper2 docs.

type end_type = [
  1. | `Polygon
    (*

    paths are assumed to be closed and treated as polygons

    *)
  2. | `Joined
    (*

    ends are joined and the paths are treated as polylines

    *)
  3. | `Butt
    (*

    ends are squared off without any extrusion

    *)
  4. | `Square
    (*

    ends extend the offset amount while being squared off

    *)
  5. | `Round
    (*

    ends extend the offset amount while being rounded off

    *)
]

Sets whether paths are treated as closed (`Polygon) when offsetting or open (and how to do so, if so). Visual examples are available in the Clipper2 docs.

type ('cpp, 'ctr) t

Clipper2 paths and polygons

This GADT abstracts over the Clipper2 Path and Paths types in order to avoid splitting the interface into two largely duplicated modules. The 'ctr parameter specifies the corresponding OCaml type from which it can be constructed from, or destructed to.

type path = ([ `Path ], V.t list) t

The Clipper2 path type (std::vector of point)

type paths = ([ `Paths ], V.t list list) t

The Clipper2 paths type (std::vector of path)

These lists of contours are not organized hierarchically (by parent-child / outer-hole) relationships, and may include any number of open paths or polygons.

module Rect : sig ... end

An axis-aligned rectangle used bounding box computations and quick rectangular clipping (boolean intersection) operations. (see rect_clip)

Construction / Conversion

val path : V.t list -> path

path ps

Create a path from the list of 2d points ps.

val paths : V.t list list -> paths

paths ps

Create paths from the list of lists of 2d points ps.

val contour : (_, 'contour) t -> 'contour

contour t

Convert the path (or paths) t to contour(s) of 2d points.

val of_poly : V.t list list -> paths

of_poly p

Create a paths from a polygon p.

val of_polys : V.t list list list -> paths

of_polys ps

Create a paths from a list of polygons ps.

val to_poly : path -> V.t list list

to_poly t

Create a polygon with the outline t.

val to_polys : ?fill_rule:fill_rule -> ('cpp, 'ctr) t -> V.t list list list

to_polys ?fill_rule t

Extract a list of non-overlapping polygons from the set of paths t. This involves a clipper union operation tracking the parent-child (outline-hole) relationships of the paths, thus fill_rule can be provided to override the default rule if desired.

val ellipse : ?fn:int -> ?centre:V.t -> V.t -> path

ellipse ?fn ?centre rs

Draw an elliptical path with with the specified xy radii rs centred on the origin, or at the point centre if provided. The number of segments can be set explicitly with fn, otherwise the quality is calculated based on the dimensions.

Access

val n_pts : ('cpp, 'ctr) t -> int

n_pts t

Return the number of points in the path(s) t.

val n_pts_sub : paths -> int -> int

n_pts_sub t i

Return the number of points in the ith sub-path of t.

val n_paths : ('cpp, 'ctr) t -> int

n_paths t

Return the number of paths in t.

val subpath : paths -> int -> path

subpath t i

Get the ith subpath from the paths t.

val path_pt : path -> int -> V.t

path_pt t i

Get the point at index i from the path t.

val paths_pt : paths -> int -> int -> V.t

paths_pt t i

Get the point at index j from the path at index i of t.

val (.%()) : path -> int -> V.t

path.%(i) gets the point at index i from path.

val (.%{}) : paths -> (int * int) -> V.t

paths.%(i, j) gets the point at index j from the ith path in paths.

Boolean Operations

val boolean_op : ?fill_rule:fill_rule -> op:clip_type -> ('cpp, 'ctr) t -> ('cpp, 'ctr) t list -> paths

boolean_op ?fill_rule ~op subjects clips

Perform the boolean operation op with the specified fill_rule on the polygons (closed paths) subjects and list of clipping polygons clips.

val intersect : ?fill_rule:fill_rule -> ('cpp, 'ctr) t list -> paths

intersect ?fill_rule ts

Intersect the list of polygons ts according to fill_rule. The result includes regions covered by all polygons.

val union : ?fill_rule:fill_rule -> ('cpp, 'ctr) t list -> paths

union ?fill_rule subjects

Union the polygons subjects according to fill_rule. The result includes the regions covered by any of the polygons contained in subjects.

val add : ?fill_rule:fill_rule -> ('cpp, 'ctr) t -> ('cpp, 'ctr) t -> paths

add ?fill_rule a b

union the polygon a and b.

val difference : ?fill_rule:fill_rule -> ('cpp, 'ctr) t -> ('cpp, 'ctr) t list -> paths

difference ?fill_rule subjects clips

Difference the polygons clips from the polygon subjects according to fill_rule. The result includes the regions covered by the polygon subjects, but not clips.

val sub : ?fill_rule:fill_rule -> ('cpp, 'ctr) t -> ('cpp, 'ctr) t -> paths

sub a b

Difference the polygon b from a (alias to difference).

val xor : ?fill_rule:fill_rule -> ('cpp, 'ctr) t list -> paths

xor ?fill_rule ts

Perform the exclusive-or boolean operation between the closed ps a and b according to fill_rule. The result includes regions covered by the either a or b, but not both.

val rect_clip : ?closed:bool -> Rect.t -> ('cpp, 'ctr) t -> paths

rect_clip ?closed r t

Intersect the path t with the axis-aligned rectangle r. The path is treated as closed/polygonal by default, but an open path may be clipped by setting ~closed:false.

Offsetting

val inflate : ?miter_limit:float -> ?join_type:join_type -> ?end_type:end_type -> delta:float -> ('cpp, 'ctr) t -> paths

inflate ?miter_limit ?join_type ?end_type ~delta t

Offset the polygon (or open path) t by delta. If t is a closed polygonal path, it's important that end_type is `Polygon (default if not overridden by user's Config). If instead you select one of the open path end types (e.g. `Joined), the polygon's outline will be inflated (example).

  • The miter_limit sets the maximum distance in multiples of delta that vertices can be offset from their original positions with join_type `Miter before squaring is applied (default is 2., which is the minimum allowed -- Invalid_argument is raised otherwise). See the Clipper2 MiterLimit) page for a visual example.
  • with closed paths (polygons), a positive delta specifies how much outer polygon contours will expand and how much inner "hole" contours will contract (and the converse with negative deltas).
  • with open paths (polylines), including `Joined, delta specifies the width of the inflated line.
  • Caution: offsetting self-intersecting polygons may produce unexpected results.

Minkowski

val minkowski_sum : ?closed:bool -> ?fill_rule:fill_rule -> pattern:path -> ('cpp, 'ctr) t -> paths

minkowski_sum ?closed ~pattern t

Apply Minkowski addition of the path pattern to the path(s) t. t is treated as a closed polygon(s) unless otherwise specified.

val minkowski_diff : ?closed:bool -> ?fill_rule:fill_rule -> pattern:path -> ('cpp, 'ctr) t -> paths

minkowski_diff ?closed ~pattern t

Apply Minkowski subtraction of the path pattern from the path(s) t. t is treated as a closed polygon(s) unless otherwise specified.

Path Simplification

val simplify : ?closed:bool -> ?eps:float -> ('cpp, 'ctr) t -> ('cpp, 'ctr) t

simplify ?closed ?eps t

Remove extraneous vertices from the path t (similar to ramer_douglas_peucker).

val ramer_douglas_peucker : ?eps:float -> ('cpp, 'ctr) t -> ('cpp, 'ctr) t

ramer_douglas_peucker ?eps t

Applies the Ramer-Douglas-Peucker algorithm to remove extraneous vertices from the path t. Put simply, vertices will be removed if they are less than eps distance from imaginary lines passing through their adjacent vertices.

This function is particularly useful following offsetting (ie inflating/shrinking paths). Offsetting often creates tiny segments that don't improve path quality. Further these tiny segments create angles that are strongly influenced by integer rounding. While these tiny segments are too small to be noticeable following a single offset procedure, they're likely to degrade the quality of subsequent offsets. And they'll also degrade performance. Because of this, it is strongly recommended calling this function after every polygon offset.

val trim_collinear : ?closed:bool -> ('cpp, 'ctr) t -> ('cpp, 'ctr) t

trim_collinear ?closed t

Remove collinear points (that fall on a line drawn between their neighbours) from the path t. The path is treated as closed by default.

val strip_near_equal : ?closed:bool -> ?eps:float -> ('cpp, 'ctr) t -> ('cpp, 'ctr) t

strip_near_equal ?closed ?eps t

Remove adjacent points that are less than eps distance apart from their neighbour from the paths t. The path is treated as closed by default.

val strip_duplicates : ?closed:bool -> ('cpp, 'ctr) t -> unit

strip_duplicates ?closed ?eps t

Remove adjacent points that duplicate of their neighbours from the paths t (inplace). The path is treated as closed by default.

Transformation

val translate : V.t -> ('cpp, 'ctr) t -> ('cpp, 'ctr) t

translate v t

Translate the path t along the vector v.

val map : (V.t -> V.t) -> ('cpp, 'ctr) t -> ('cpp, 'ctr) t

map f t

Map over the points in t with the function f.

Geometry

val area : ('cpp, 'ctr) t -> float

area t

Compute the signed area of the path t.

val bounds : ('cpp, 'ctr) t -> Rect.t

bounds t

Compute the axis-aligned bounding box that contains the path t.

val is_positive : path -> bool

is_positive t

Check if the orientation/winding of the path t is positive.

val point_inside : path -> V.t -> [> `Inside | `OnBorder | `Outside ]

point_inside t p

Determine whether the point p is inside, outside, or on the border of t.

Export

module Svg : sig ... end

Utilities for writing (and reading) simple SVGs, for use in debugging and quick visualization.