Skip to content

Geometry, matrices and coordinates

Queries on drawings, geometry calls, matrices, OGL conversion and the value classes.

These calls answer questions about a drawing's lines, work on paths you hold, and move between the scene's coordinates and the units a renderer uses. They read the scene and change nothing.

Questions about a drawing

buhayin.closestPoint(layer, which)

await buhayin.closestPoint(layer, { frame | drawing, art?, x, y, maxDistance? })

The line of a drawing nearest a point. Name the drawing with frame or drawing, give the point as x and y, and limit the search with maxDistance if you like. The answer holds the mark, its index in the drawing as strokeIndex, the point on it, t along its outline and the distance.

const near = await buhayin.closestPoint("Body", { frame: 1, x: 120, y: 40 })

buhayin.intersections(layer, which)

await buhayin.intersections(layer, { frame | drawing, art?, paths, computeIntersections? })

Where each path crosses the lines of a drawing. A path is { path: [{ x, y, onCurve? }], polygon? }.

The answer is false when no path meets a line. Otherwise there is an entry for each line a path crosses or has an end inside. An entry holds layer (the art layer's number, bottom first from 0), strokeIndex (the line's place among the marks of that art layer) and mark (its id). Unless computeIntersections is off, each crossing is x0, y0, t0 on the path, x1, y1, t1 on the line, and x, y, the first point to a 64th.

const hit = await buhayin.intersections("Body", {
  frame: 1,
  paths: [{ path: [{ x: 0, y: 0 }, { x: 200, y: 200 }] }],
})
print(hit === false ? "No line crossed." : hit.length + " lines crossed.")

Paths you hold

buhayin.geometry works on a path you give it, with no drawing behind it. A path is a list of points, { x, y, onCurve? }. Every path comes back with onCurve on each point, so it can go straight to another call. A path may hold at most 10,000 points and a call at most 1,000 parameters.

buhayin.geometry.fit(args)

await buhayin.geometry.fit({ path, closed?, oneBezier? })

Fits a path through points. By default every point is a corner, fitted at a tolerance of one drawing unit. With oneBezier the answer is one cubic through the points, ended on its start when closed.

buhayin.geometry.discretize(args)

await buhayin.geometry.discretize({ path, closed?, precision? })

Cuts a path with handles into points, a segment at a time. precision is how many output units to a drawing unit and is 0.1 unless you give one. A precision below 0.001 is refused and one above 100 is taken as 100. At most 100,000 points come back.

buhayin.geometry.split(args)

await buhayin.geometry.split({ path, closed?, params })

Cuts the path at each parameter and answers the pieces. A parameter is a segment's number counting from 0 plus the share of that segment already passed, so 1.5 is halfway along the second segment.

buhayin.geometry.insertPoints(args)

await buhayin.geometry.insertPoints({ path, closed?, polygon?, params })

Puts each parameter in as a curve point, cutting the path there, and answers the one path. split and insertPoints answer false for a path with fewer than two curve points.

buhayin.geometry.pathIsContaining(args)

await buhayin.geometry.pathIsContaining({ path, polygon?, points })

For each point, whether the closed path holds it, by the nonzero rule.

const inside = await buhayin.geometry.pathIsContaining({
  path: [{ x: 0, y: 0 }, { x: 100, y: 0 }, { x: 100, y: 100 }, { x: 0, y: 100 }],
  points: [{ x: 50, y: 50 }, { x: 150, y: 50 }],
})

Where a layer stands

buhayin.matrix(layer, frame)

await buhayin.matrix(layer, frame)

Where a row stands on a frame. The answer holds world (its world matrix), depth, pivot and view, and joint for a joint of a chain, which stands in its bone's pose.

buhayin.cameraMatrix(frame)

await buhayin.cameraMatrix(frame)

The camera's view on a frame.

Field coordinates and OGL units

The scene's field chart sets how far a unit of the field is from the centre. These calls convert by that chart.

await buhayin.toOGL({ x, y, z?, vector? })
await buhayin.fromOGL({ x, y, z?, vector? })
await buhayin.toOGLX(x)    // also toOGLY, toOGLZ
await buhayin.fromOGLX(x)  // also fromOGLY, fromOGLZ

A point is moved by the chart's centre across and down. With vector: true it is only scaled. Give a Point3d, Vector2d or Vector3d and you get the same class back. A plain { x, y, z? } comes back plain. toOGLX and the other five take one number on one axis.

const p = await buhayin.toOGL({ x: 0, y: 0 })

Value classes

These are plain globals. They hold their numbers in a typed array, so x, y and z are properties.

ClassMade withWhat it is for
Point2d(x, y)A function, no newA flat point.
ColorRGBA(r, g, b, a)A function, no newA colour, 0 to 255 for each channel, a defaulting to 255.
new Vector2d(x, y)Zero or two numbersA flat direction.
new Vector3d(x, y, z)Zero or three numbersA direction in space.
new Point3d(x, y, z)Zero or three numbersA point in space.
new Matrix4x4()No argumentsA 4 by 4 transform.
new Quaternion(x, y, z, w)Zero or four numbersA turn. With no arguments it is the identity.

What each can do:

  • Vector2d: isZero, isEqual, isNotEqual, length, lengthSq, radianAngle, degreeAngle, dot, rotate(radians), rotate90, rotate270, project, getProjection, normalize, getNormalized, negate.
  • Vector3d: setXYZ, isZero, isEqual, isNotEqual, length, lengthSq, getCos, getSin, cross, getProjectionRatio, getProjection, project, getNormalized, normalize.
  • Point3d: setXYZ, isOrigin, isEqual, isNotEqual, distance, distanceSq, round(quantum), interpolate(t, first, second), add(vector), minus(other), addEq, minusEq, toPoint2d.
  • Matrix4x4: value(row, column), axis(index), origin, clear, multiply, translate, rotatePlane, orthogonalProject, perspectiveProject, setFromEulerAngles, print.
  • Quaternion: setWXYZ, getConjugate, getInverse, isIdentity, isEqual, isNotEqual, toEuler, fromEuler, getDotProduct, multiply, getNormalized, rotateVector.
const a = new Vector3d(1, 0, 0)
const b = new Vector3d(0, 1, 0)
const c = a.cross(b)        // (0, 0, 1)
print(c.x, c.y, c.z)

The arithmetic runs inside the script, so these calls need no round trip to the editor.