Drawing/geometry

This module provides functions to generate geometry like circle or rectangle or manipulate Bezier paths.

Notes:
  • The units for the drawings in the Toon Boom Animation's vector drawing are in the range [-2500, 2500] for the x axis of a 12 field grid. Since the grid has an aspect ratio of 4/3, the vertical range (y axis) is in the [-1875, 1875] range. The Toon Boom Animation's vector drawing coordinate system is not finite which means coordinates can be bigger than the 2500 value of the 12 fields. For numerical stability reasons, it is not recommended to use coordinates higher than 64000 because for very big numbers, there will be a loss of precision on the fractional part of the numbers.

Methods

(static) createCircle(arg) → {Array.<{x: double, y: double, onCurve: boolean}>}

This function returns a bezier path that approximates a circle with 4 cubic beziers
Example
var arg = {
    x : 12, y : 12, radius : 100
 };
 var circle = Drawing.geometry.createCircle(arg);
 // circle will contain:
 circle = [
   {"x":12,"y":-88,"onCurve":true},
   {"x":67.22847747802734,"y":-88},
   {"x":112,"y":-43.22847366333008},
   {"x":112,"y":12,"onCurve":true},
   {"x":112,"y":67.22847747802734},
   {"x":67.22847747802734,"y":112},
   {"x":12,"y":112,"onCurve":true},
   {"x":-43.22847366333008,"y":112},
   {"x":-88,"y":67.22847747802734},
   {"x":-88,"y":12,"onCurve":true},
   {"x":-88,"y":-43.22847366333008},
   {"x":-43.22847366333008,"y":-88},
   {"x":12,"y":-88,"onCurve":true}
 ];
Parameters:
Name Type Description
arg Object Parameters for the generated circle
Properties
Name Type Attributes Description
x double The x coordinate of the center of the circle.
y double The y coordinate of the center of the circle.
radius double The radius of the circle. This parameter is mandatory if radiusX and radiusY are not used.
radiusX double <optional>
 The x radius of the circle in the case of an ellipse.
radiusY double <optional>
 The y radius of the circle in the case of an ellipse.
Returns:
A Bezier path
Type
Array.<{x: double, y: double, onCurve: boolean}>

(static) createRectangle(box)

This function returns a rectangular bezier path
Example
var box = {
    x0 : 0, 
    y0 : 0,
    x1 : 100,
    y1 : 100 
 };
 var boxPath = Drawing.geometry.createRectangle(box);
 // boxPath will contain:
 boxPath = [
   {"x":0,"y":0,"onCurve":true},
   {"x":100,"y":0,"onCurve":true},
   {"x":100,"y":100,"onCurve":true},
   {"x":0,"y":100,"onCurve":true},
   {"x":0,"y":0,"onCurve":true}
];
Parameters:
Name Type Description
box Box2d
Properties
Name Type Description
x0 double The min x coordinate.
x1 double The max x coordinate.
y0 double The min y coordinate.
y1 double The max y coordinate.

(static) discretize(arg) → {Array.<{x: double, y: double}>}

This function returns a polyline from a cubic or quadratic bezier path
Example
var arg = {
    precision: 1,
    path : [ 
    { x : 0, y: 0, onCurve: true },
    { x : 10, y: 0, onCurve: false },
    { x : 20, y: 20, onCurve: false },
    { x : 30, y: 20, onCurve: true } ] 
 };
 var path = Drawing.geometry.discretize(arg); // path contains a discretized version of the path in arg
 // path will contain:
 path = [
 {"x":0,"y":0,"onCurve":true},
 {"x":3.75,"y":0.859375,"onCurve":true},
 {"x":7.5,"y":3.125,"onCurve":true},
 {"x":15,"y":10,"onCurve":true},
 {"x":22.5,"y":16.875,"onCurve":true},
 {"x":26.25,"y":19.140625,"onCurve":true},
 {"x":30,"y":20,"onCurve":true}];
Parameters:
Name Type Description
arg Object A dictionary of options
Properties
Name Type Attributes Description
precision double <optional>
 The needed precision. 0-100.
path Array.<BezierPoint> The Bezier path to be discretized.
Properties
Name Type Description
x double
y double
onCurve boolean If true, the point is on the curve. If false, it means the vertex is a control point. There cannot be more that 2 consecutive control points.
Returns:
Type
Array.<{x: double, y: double}>

(static) evaluate(arg) → {Array.<{x:double, y:double, t:double}>}

This function evaluates a bezier path at different parameter values
Example
var arg = {
    path : [ 
    { x : 0, y: 0, onCurve: true },
    { x : 10, y: 0, onCurve: false },
    { x : 20, y: 20, onCurve: false },
    { x : 30, y: 20, onCurve: true } ],
    params : [ 0.5 ]  
 };
 var values = Drawing.geometry.evaluate(arg);
 // values will contain:
 values = [{"x":15,"y":10,"t":0.5}];
Parameters:
Name Type Description
arg Object
Properties
Name Type Description
path Array.<BezierPoint> The Bezier path to be discretized.
Properties
Name Type Description
x double
y double
onCurve boolean If true, the point is on the curve. If false, it means the vertex is a control point. There cannot be more that 2 consecutive control points.
params Array.<double> A list parameters to evaluate the path at.
Returns:
Type
Array.<{x:double, y:double, t:double}>

(static) fit(arg) → {Array.<BezierPoint>}

This function returns a fitted bezier path from a polyline bezier path
Example
// The onCurve can be omitted for the fit method because in this context, all the points are on the curve.
 var arg = {
    oneBezier: true,
    path: [
       { x: 0, y: 0 },
       { x: 10, y: 1 },
       { x: 15, y: 1 },
       { x: 18, y: 2 },
       { x: 20, y: 1 }
    ]
 };
 var fitted = Drawing.geometry.fit(arg);
 // fitted will contain:
 fitted =  [
 { "x": 0, "y": 0, "onCurve": true },
 { "x": 6.654067516326904, "y": 0.31957897543907166 },
 { "x": 13.62016773223877, "y": 1.9861396551132202 },
 { "x": 20, "y": 1, "onCurve": true}
]
Parameters:
Name Type Description
arg Object
Properties
Name Type Attributes Description
oneBezier boolean <optional>
 If true, fits a single bezier otherwise generates a bezier path with any number of beziers.
path Array.<Point2d>
Properties
Name Type Description
x double
y double
Returns:
Type
Array.<BezierPoint>

(static) getClosestPoint(arg)

Returns the closest point to each points of a list
Example
var arg = {
      path : [ {x: 0, y: 0, onCurve: true}, {x: 100, y: 0, onCurve: true} ], 
      points : [ { x : 10, y: 12 } ]
   }
   var closest = Drawing.geometry.getClosestPoint(arg);
  // closest contains:
  [
   {
    "x":10,"y":12, // The coordinate of the tested point
    "maxDistanceSq":244,  // The max distance used
    "closestPoint":{
      "distanceSq": 144,
      "distance":12,
      "t":0.1,
      "x":10,"y":0
      }
    }
   ]
Parameters:
Name Type Description
arg Object
Properties
Name Type Description
path Array.<BezierPoint> The bezier path.
points Array.<Point2d> List of points.
Properties
Name Type Description
x double X coordinate of the point.
y double Y coordinate of the point.
maxDistanceSq double Square of the maximum allowed distance.

(static) getIntersections(arg)

This function returns intersections from bezier paths
Example
var arg = {
    path0 : { path : [ {x: 0, y: 0, onCurve: true}, {x: 100, y: 100, onCurve: true} ] }, 
    path1 : { path : [ {x: 100, y: 0, onCurve: true}, {x: 0, y: 100, onCurve: true} ] } 
 };
 var intersections = Drawing.geometry.getIntersections(arg);
 // intersections will contain:
 intersections = [
   {
     "x0":50,"y0":50,  // The path0 evaluated at the intersection point without rounding
     "t0":0.5,         // The intersection parameter on path0 
     "x1":50,"y1":50,  // The path1 evaluated at the intersection point without rounding
     "t1":0.5,         // The intersection parameter on path1
     "x":50,"y":50     // The rounded intersection point. Rounded to the resolution of the vector model.
    }
  ]
Parameters:
Name Type Description
arg Object
Properties
Name Type Description
path0 Array.<BezierPoint> The first Bezier path
path1 Array.<BezierPoint> The second Bezier path

(static) insertPoints(arg) → {Array.<BezierPoint>}

This function insert points at the given parameters t on a Bezier path
Example

Insertion of two points on a line segment. Note that insert points for param < 0 or param >= the number of beziers in a path will not do anything. Also, inserting point on an integer parameter will not insert new point. 

   var arg = {
      path : [ {x: 0, y: 0, onCurve: true}, {x: 100, y: 100, onCurve: true} ], 
      params : [ 0.25, 0.5, 0.75]
   }
   var newPath = Drawing.geometry.insertPoints(arg);
  // newPath now contains:
  newPath = [
  {"x":0,"y":0,"onCurve":true},
  {"x":25,"y":25,"onCurve":true},
  {"x":50,"y":50,"onCurve":true},
  {"x":75,"y":75,"onCurve":true},
  {"x":100,"y":100,"onCurve":true}
  ];
Parameters:
Name Type Description
arg Object
Properties
Name Type Description
path Array.<BezierPoint> The bezier path.
params Array.<double> Parameters to insert points at.
Returns:
A Bezier path
Type
Array.<BezierPoint>

(static) pathIsContaining(arg) → {Array.<boolean>}

This function returns true if points provided in an array a contained withing a closed bezier path
Example
var arg = {
      path: Drawing.geometry.createCircle({x: 0, y: 0, radius: 50}),
      points: [ {x: 0, y: 0}, { x: 1000, y: 0} ]
   };
   var result = Drawing.geometry.pathIsContaining(arg);  // result will be:  [ true, false ]
Parameters:
Name Type Description
arg Object
Properties
Name Type Description
path Array.<BezierPoint> The closed bezier path.
points Array.<Point2d> The 2d points to test.
Returns:
An array of boolean values
Type
Array.<boolean>

(static) split(arg) → {Array.<Array.<BezierPoint>>}

This function splits a Bezier path in different paths at given parameters
Example
var arg = {
      path : [ {x: 0, y: 0, onCurve: true}, {x: 100, y: 100, onCurve: true} ], 
      params : [ 0.25, 0.5]
  }
  var pathList = Drawing.geometry.split(arg);
  // pathList now contains:
  pathList = [
     [{"x":0,"y":0,"onCurve":true},{"x":25,"y":25,"onCurve":true}],    // [0-0.25]
     [{"x":25,"y":25,"onCurve":true},{"x":50,"y":50,"onCurve":true}],  // [0.25-0.5]
     [{"x":50,"y":50,"onCurve":true},{"x":100,"y":100,"onCurve":true}] // [0.5-1.0]
  ];
Parameters:
Name Type Description
arg Object
Properties
Name Type Description
path Array.<BezierPoint> The bezier path.
params Array.<double> Parameters to split at.
Returns:
A list of Bezier path
Type
Array.<Array.<BezierPoint>>

(inner) getConstants() → {GeometryConstants}

This function returns the constants used in the geometry computations
Example
var constants = Drawing.geometry.getConstants();
// constants now contains: 
 constants = {
   "splitPerimeter":4,        // When computing intersection, bezier with a perimeter bigger than this value will be split recursively.
   "roundingQuantum":0.015625 // All points in the vector model are rounded to this precision which is 1.0 / 64.0.
 };
Returns:
The constants used in the geometry computations
Type
GeometryConstants