Skip to main content

Moving, turning and placing shapes

bitbybit.occt.transforms moves shapes without changing their form. Like every operation, a transform returns a new shape and leaves the one you gave it where it was.

The everyday moves​

  • Move: translate by a vector, in model units.
  • Turn: rotate about an axis through the origin, or rotateAroundCenter about an axis through any point, by an angle in degrees with the right-hand rule.
  • Resize: scale uniformly about the origin, scaleFromCenter about a point, or scale3d by a different factor along X, Y and Z.
  • Mirror: mirrorAlongNormal across a plane, the usual mirror image a symmetric part needs; mirror across a line and mirrorAboutPoint through a point.
  • All at once: transform scales, turns and moves in one call, in that order.

Most of them have a ...Shapes twin that moves several shapes, each by its own amount.

Frames: put this here, facing that way​

A frame is a point with three axes: where something sits and which way it faces. The bitbybit.frame functions make them: one frame (create, zx for the ground), or many in a pattern (grid, polar for a ring, hexGrid).

Frames let you place a shape without working out angles:

  • orient moves a shape from one frame onto another in a single rigid motion;
  • align and alignNormAndAxis do the same from a point and directions on the shape;
  • placeOnFrames puts a copy of the shape on every frame of a list.

placeOnFrames keeps one shape's geometry and only records where each copy sits, so a hundred bolts cost little more than one, and an export writes the bolt once. Here one block is placed on twelve frames of a ring on the ground:

Bitbybit Platform

A block placed on a ring of frames in Rete

rete logoRete
Script Source (rete)
{
  "id": "rete-v2-json",
  "nodes": {
    "block": {
      "id": "block",
      "name": "bitbybit.occt.shapes.solid.createBox",
      "customName": "box",
      "async": true,
      "drawable": true,
      "data": {
        "genericNodeData": {
          "hide": true,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "width": 1,
        "length": 1,
        "height": 2.5,
        "center": [
          0,
          0,
          0
        ],
        "originOnCenter": true
      },
      "inputs": {},
      "position": [
        40,
        40
      ]
    },
    "ground": {
      "id": "ground",
      "name": "bitbybit.frame.zx",
      "customName": "zx",
      "async": false,
      "drawable": true,
      "data": {
        "genericNodeData": {
          "hide": true,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "origin": [
          0,
          0,
          0
        ]
      },
      "inputs": {},
      "position": [
        40,
        460
      ]
    },
    "ring": {
      "id": "ring",
      "name": "bitbybit.frame.polar",
      "customName": "polar",
      "async": false,
      "drawable": true,
      "data": {
        "genericNodeData": {
          "hide": true,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        },
        "count": 12,
        "radius": 6,
        "angle": 360,
        "startAngle": 0,
        "rotate": true
      },
      "inputs": {
        "frame": {
          "connections": [
            {
              "node": "ground",
              "output": "result",
              "data": {}
            }
          ]
        }
      },
      "position": [
        460,
        460
      ]
    },
    "place": {
      "id": "place",
      "name": "bitbybit.occt.transforms.placeOnFrames",
      "customName": "place on frames",
      "async": true,
      "drawable": true,
      "data": {
        "genericNodeData": {
          "hide": false,
          "oneOnOne": false,
          "flatten": 0,
          "forceExecution": false
        }
      },
      "inputs": {
        "shape": {
          "connections": [
            {
              "node": "block",
              "output": "result",
              "data": {}
            }
          ]
        },
        "frames": {
          "connections": [
            {
              "node": "ring",
              "output": "result",
              "data": {}
            }
          ]
        }
      },
      "position": [
        880,
        40
      ]
    }
  },
  "modules": {}
}

The frames of a polar ring turn with the ring, so each copy faces outwards; set rotate off and every copy keeps the same heading.

Matrices​

For moves built up from many steps, the ...ToMatrix functions turn each move into a 4x4 matrix, multiplyTransforms chains them into one, and transformByMatrix applies the result. getShapeTransform reads the placement a shape carries.

Every transform​

FunctionWhat it does
alignMoves a shape so that one point and direction on it land on another point and direction: the frame fromOrigin with fromDirection is carried onto toOrigin with toDirection.
alignAndTranslateTurns a shape so that its Y axis points along direction, then moves it to center.
alignAndTranslateShapesApplies alignAndTranslate to several shapes, each with its own direction and center.
alignNormAndAxisMoves a shape so that a full frame on it lands on another frame: a point, its normal and one axis in the plane of that normal are carried onto their targets.
alignShapesApplies align to several shapes, each with its own from and to frames.
composeTransformBuilds one matrix from a translation, three rotation angles in degrees about X, Y and Z, and a uniform scale.
getShapeTransformReads the placement a shape carries, the transform stored on it rather than baked into its geometry, as a matrix plus its translation, rotation quaternion and uniform scale.
identityTransformBuilds the identity matrix, the transform that changes nothing, as a starting point for composing others.
invertTransformInverts a matrix, giving the transform that undoes it: applying a matrix and then its inverse puts a shape back where it was.
mirrorMirrors a shape across a line: the axis through origin along direction.
mirrorAboutPointMirrors a shape through a point: every point of the shape lands as far beyond the point as it was before it, on the opposite side.
mirrorAlongNormalMirrors a shape across a plane given by a point on it and its normal.
mirrorAlongNormalShapesApplies mirrorAlongNormal to several shapes, each across its own plane.
mirrorAxisToMatrixBuilds the matrix of a mirror across a line, the transform mirror applies: the axis through origin along direction.
mirrorPlaneToMatrixBuilds the matrix of a mirror across a plane, the transform mirrorAlongNormal applies: the plane through origin with the given normal.
mirrorPointToMatrixBuilds the matrix of a mirror through a point, the transform mirrorAboutPoint applies.
mirrorShapesApplies mirror to several shapes, each across its own axis.
multiplyTransformsFolds a list of matrices into one, applied first to last, so a chain of moves becomes a single matrix.
orientMoves a shape from one frame onto another in a single rigid motion: whatever sat on from sits the same way on to.
placeByMatricesPlaces a copy of a shape by every placement, a matrix or a list of them, in one compound whose copies share the shape's geometry.
placeOnFramesPlaces a copy of a shape on every frame, as orient would move it from from, all in one compound whose copies share the shape's geometry: an array of hundreds costs one shape's worth of geometry, and an export writes it once.
quaternionToMatrixBuilds the rotation matrix of a quaternion given as [x, y, z, w].
rotateRotates a shape about an axis that passes through the origin, by an angle in degrees.
rotateAroundCenterRotates a shape about an axis that passes through a chosen point, by an angle in degrees.
rotateAroundCenterShapesApplies rotateAroundCenter to several shapes, each with its own angle in degrees, center and axis.
rotateByQuaternionRotates a shape about the origin by a quaternion given as [x, y, z, w].
rotateShapesApplies rotate to several shapes, each about its own axis through the origin and by its own angle in degrees.
rotationAxisAngleToMatrixBuilds the matrix of a rotation by an angle in degrees about an axis, through the origin or through an optional center point.
scaleScales a shape uniformly about the origin by a factor.
scale3dScales a shape by a separate factor along X, Y and Z, about a chosen center point.
scale3dShapesApplies scale3d to several shapes, each with its own three factors and center.
scaleFromCenterScales a shape uniformly about a chosen point by a factor.
scaleShapesApplies scale to several shapes, each uniformly about the origin by its own factor.
scaleUniformToMatrixBuilds the matrix of a uniform scale by a factor about the origin or an optional center point.
transformScales, rotates and moves a shape in one go: first the scale about the origin, then the rotation about an axis through the origin, then the translation.
transformByMatrixApplies a 4x4 matrix, or a list of matrices applied first to last, to a shape.
transformShapesApplies transform to several shapes, each with its own translation, rotation axis, angle and scale factor.
transformShapesByMatrixApplies the same 4x4 matrix, or list of matrices applied first to last, to several shapes, as transformByMatrix does for one.
translateMoves a shape by a vector, in model units.
translateShapesApplies translate to several shapes, each by its own vector.
translationToMatrixBuilds the matrix of a move by a vector, in model units.