Skip to main content

Function: updatePlaneRestriction()

updatePlaneRestriction(points, reference, viewRefSpecifier): PlaneRestriction

Updates the planeRestriction(s) inside the view reference This will create a reference containing a point and up to two non-collinear in-plane vectors, selected from the set of points provided.

This type of reference restricts the allowed camera views to those which contain the point, and whose view plane normal is orthogonal to the in plane vectors.

A plane restriction states which views are COMPATIBLE with the data. A plane restriction does not restore a view, so the function never records more orientation than the points themselves give. The number of points sets how much the restriction can say:

  • one point gives a position and no orientation, so the restriction holds no in-plane vector, and every plane through the point is compatible;
  • two points give one direction, so the restriction holds inPlaneVector1 only, and every plane that contains that direction is compatible;
  • three or more points pin a plane, so the restriction can hold both vectors. The camera supplies an exact pair from its cross products, and that pair describes the same plane, so the function keeps an existing pair in this case.

reference.viewUp and reference.viewPlaneNormal restore a view. See the PlaneRestriction type for the split between the two jobs.

Parameters​

• points: Point3[]

the points that the reference must contain. The function reads this argument, and NOT viewRefSpecifier.points.

• reference: ViewReference

the view reference, and NOT reference.planeRestriction. This function does reference.planeRestriction ||= ..., so it needs the outer object. A PlaneRestriction also structurally satisfies the all-optional ViewReference, so a call that passes the inner object type checks, but then builds and mutates a nested planeRestriction.planeRestriction, and silently discards the point-derived in-plane vectors.

• viewRefSpecifier: ViewReferenceSpecifier = {}

the options that the caller used to ask for the reference. The function reads forceInPlaneVectors.

Returns​

PlaneRestriction

Defined in​

packages/core/src/utilities/updatePlaneRestriction.ts:56