Skip to main content

Coordinate systems and script behaviour

Bitbybit draws the same model in three engines that do not agree on which way their axes point. This page says what that means for a script, what a script made today gets, and what happens to a script made earlier.

The short version​

  • A script made today follows the engine: every file it writes matches what the screen shows, and a shape that names a hand, such as a right-hand thread, shows that hand.
  • A script made earlier keeps behaving as it did when it was saved. Nothing you saved changes on its own.
  • An older script that uses nothing affected is moved to the new behaviour by itself, because for it the two are the same.
  • An older script that does use something affected is updated with one click, More > Update script behaviour, which lists what will change first.

Two coordinate systems​

The CAD kernels (OCCT, Manifold and JSCAD) are right-handed: with X to the right and Y up, Z points towards you. Three.js and PlayCanvas are right-handed too.

A default BabylonJS scene, which is what the coding editors draw in, is left-handed: with X to the right and Y up, Z points away from you.

The same three arms, X in red, Y in green and Z in blue, drawn from the same numbers. On the left the editor's left-handed scene, where Z runs away from you; on the right a right-handed scene, where it comes towards you.

For years Bitbybit drew the kernel's numbers into the BabylonJS scene as they were. A picture drawn that way is the mirror image of the model the kernel holds. That was invisible for a box and plainly wrong in three places:

  • a file exported from the script did not always match the picture: a part could come out mirrored, or lying on its back;
  • a named hand showed the other hand: a right-hand thread looked left-hand, and a helix asked to turn clockwise turned the other way;
  • a model read from a file that knows its own shape, such as an IFC building, was drawn mirrored.

A helical gear names its hand: a positive helixAngle asks for a right-hand gear, whose teeth lean to the right as they rise. This is such a gear drawn by a script made before scripts followed the engine, and beside it the STL file that script exports, opened in Blender. The screen and the file agree with each other, and both show a left-hand gear.

What following the engine means​

A script that follows the engine treats the numbers it works with as the engine's own. Bitbybit then makes three things true in every engine:

WhatWhat you get
A file you exportA true right-handed file that shows what the screen shows, the right way up.
A file you importA model that looks on screen as it looks in the program that made it. An assembly document read with occt.assembly.manager.loadStepToDoc is the exception: it keeps the file's own right-handed numbers at every level, so show it in a right-handed scene.
A shape that names a handThe hand it names, on screen and in the file.

In the editors the picture of an ordinary model does not change at all. What changes is listed under what changes.

The same gear from a script that follows the engine, and its file in Blender. The teeth now lean to the right, on screen and in the file.

Scripts made today​

Every script you start on bitbybit.dev follows the engine from the start. There is nothing to switch on.

In your own app built on the npm packages, say so once when you set the library up:

await initBitByBit(scene, bitbybit, { enableOCCT: true, conventions: 1 });

That is the BabylonJS and ThreeJS form; with PlayCanvas the application comes first, initBitByBit(app, scene, bitbybit, { enableOCCT: true, conventions: 1 }). Or, on a library that is already running:

await bitbybit.setConventions(1);

1 is the level of behaviour described on this page. An app that leaves it out behaves as the libraries did before, so an existing app is never changed by an update of the packages.

If you run a kernel yourself, without an engine, tell it the coordinate system directly:

import { Inputs } from "@bitbybit-dev/base";

occt.settings = { coordinateSystem: Inputs.Base.coordinateSystemEnum.rightHanded };

Scripts made earlier​

A script saved before this behaviour existed carries no mark, and runs exactly as it did. That holds in the editor, in the preview, and in a runner script you exported from it earlier.

When you open such a script, Bitbybit looks at what it uses:

  • It uses nothing affected. Most scripts are like this: they build, cut, round and draw. For them the old and the new behaviour give the same result, so the script is moved to the new behaviour by itself. You will not see a difference, and the script is saved with its new mark the next time you change it.
  • It uses something affected. The script is left as it is, and More > Update script behaviour appears. It opens a list of what will change for this script. Choose Update, look the result over, and remove anything you had added to work around the old behaviour, such as a mirror after an import or a flipped clockwise.

The entry in the More menu, and the question it opens for the gear above.

The check errs on the side of asking: a script that only has a variable named like an affected function is asked too.

What changes when a script is updated​

If the script usesThen after the update
File import and export: STEP, IGES, STL, OBJ, PLY, 3MF, DXF, SVGA file holds what the screen shows, the right way round and the right way up. With adjustYtoZ on, the file is Z-up for other CAD programs.
Helices, flat spirals, threads and helical gearsclockwise, a right-hand thread and a positive helix angle look the way they are named.
IFC models, recipes and design documents built from a scriptThey are built the way their data describes them, no longer mirrored.
Text, hexagon grids and view drawings laid on the groundThe same in the editors, and no longer mirrored in a right-handed engine.
Meshes made for a tool with Z upTurned, not mirrored, in a right-handed engine.
A BabylonJS capsule or ground with a front or back sideFront side and back side show the side they name.
A scene the script makes right-handedThe coordinate system stays the one the editor set up. To have files, text and shapes that name a hand follow the switch, the script also calls bitbybit.setSettings with the right-handed system; clearing the scene then keeps it right-handed.
3D textReads the right way round in a right-handed engine too.

What never changes​

  • The picture of an ordinary model in the editors. Boxes, booleans, fillets, sweeps and drawings of them look as they always did.
  • Which way a rotation turns. An angle that is counterclockwise stays counterclockwise.
  • Dimension labels. They read the same in both systems.
  • The Designer. It has always shown the kernel's model as it is.

Runner scripts​

More > Export to runner writes the script's level into the exported file, and a runner of this release or later reads it before it runs the script. A runner older than levels ignores the mark, so a page that pins an older runner version runs every script the earlier way, re-exported or not. A file you exported earlier has no level and keeps running as it did, in any runner. To move an embedded script to the new behaviour, update the script in the editor and export it again.

In the BabylonJS runner, a script that follows the engine gets the coordinate system its scene has when the script starts, and bitbybit.engineSettings() answers with the same one, so on a page that makes its scene right-handed, files, text and shapes that name a hand follow the right-handed system.

3D Bits configurators​

A script inside a 3D Bits configurator carries its level the same way, and the product page runs it as the editor showed it:

  • A linked script project is published with its level. One published earlier keeps running as it did until it is published again.
  • TypeScript written in Composer starts at the level described here. An older script is moved by itself the next time it is saved when what it held uses nothing affected; otherwise its editor shows Update script behaviour.
  • A pasted export or a public URL keeps its level when it holds the export itself, the exported file's content or what Copy gives. Bare code, which Copy code gives, carries no level and runs as scripts did before.

A scene set to be right-handed gives a script that follows the engine a right-handed coordinate system, and a default scene a left-handed one. Scripting in the Composer's pages covers the details.

CAD Cloud​

CAD Cloud runs every kernel right-handed, with Y up: OCCT, JSCAD and Manifold, on its own routes such as unfolding and nesting, and on every operation a pipeline or an execute call runs. A request carries no level; every request gets this behaviour.

  • Files are true right-handed files. The files CAD Cloud writes as a result (STEP, STL and 3MF) are written with Z up, so other CAD programs show the model standing; a file an operation in a pipeline writes follows that operation's own options, such as adjustYtoZ, which is off by default. A STEP file loaded with adjustZtoY is turned to Y up, never mirrored.
  • JSCAD and Manifold numbers are read as Y up too. A solid those kernels build or extrude along +Z therefore lies along the file's -Y in an STL or 3MF result, where earlier versions wrote the numbers unchanged. Build with Y up, or turn the solid a quarter about X before it is written.
  • Drawings (DXF, SVG and nesting outlines) show a shape lying on the ground as seen from above: X to the right and the model's -Z up the page.
  • Meshes and positions in a result, such as a decomposed-mesh or the transforms in a nesting report, are right-handed numbers with Y up. Show them in a right-handed scene: three.js, PlayCanvas, or a BabylonJS scene made right-handed (scene.useRightHandedSystem = true) before anything is drawn in it. A default BabylonJS scene shows them mirrored. The viewer in CAD Cloud's Studio is right-handed.

Earlier versions of CAD Cloud read a STEP file mirrored and wrote it back mirrored, and wrote JSCAD and Manifold numbers into STL and 3MF files as they were. A request that worked around that, with a mirror after loading, a flipped drawing or a turn before writing, should drop the workaround.