Skip to main content

Units

Numbers in a file are in that file's unit. The unit is metadata: it is not a scale factor applied to your numbers, and nothing converts a value on its way from your source to the geometry. extrude(30) in a millimetre file is 30 mm of extrusion; in an inch file it is 30 in.

The default is millimetres. A file without unit() in a project without "unit" in fluidcad.json behaves exactly as FluidCAD always has.

Choosing a unit​

There are two places to set it, and one always wins over the other:

  1. Per file — unit('in') at the top of a part file.
  2. Per project — "unit": "in" in fluidcad.json, the default for every file that does not declare its own.

Supported units: mm, cm, m, in, ft. Aliases such as 'inch', 'inches', 'millimeter' or 'feet' are accepted and canonicalised.

unit() in a file​

import { unit, sketch, circle, extrude, fillet } from 'fluidcad/core';

unit('in');

sketch("xy", () => {
    circle([0, 0], 2);      // 2 in
});
const boss = extrude(0.75); // 0.75 in
fillet(0.125, boss.endEdges());

The statement has four rules; breaking one is a compile error that points at the offending line:

  • Top level only — not inside part(), sketch() or any function.
  • Before any geometry — after the imports, ahead of the first modelling call in the file. Put it above param() declarations too.
  • Once per file.
  • A literal string — unit('in'), never unit(myUnit). Tooling reads the unit without running your code.

unit() applies to the file it is written in, including every part() definition that file exports. Importing a file does not import its unit.

Converting a single value​

Sometimes one dimension arrives in the other system — a 1/4-20 thread in a metric bracket, a 3.2 mm pin in an inch fixture. Convert that value instead of switching the whole file:

import { sketch, circle, extrude } from 'fluidcad/core';
import { inch, mm } from 'fluidcad/units';

// an mm file
sketch("xy", () => {
    circle([0, 0], inch(0.25));   // 6.35
});
extrude(inch(1));                 // 25.4

mm(), cm(), m(), inch() and ft() each convert a value into the unit of the file that calls them. inch(1) is 25.4 in a millimetre file and 1 in an inch file, so the helper reads the same whichever unit the file is in. (in is a reserved word in JavaScript, hence inch.)

The helpers only work inside a render; they throw when called from code that is not part of a FluidCAD file.

Feature defaults​

Defaults are plain numbers in document units and do not change with the unit: fillet() with no radius is 1, chamfer() is 1, text() size is 10, and so on. In an inch file, fillet(e.endEdges()) is a one-inch fillet. Pass the size you mean.

Assemblies​

Units belong to parts. unit() in a *.assembly.js file is an error.

  • An assembly's own lengths — mate .offset(), .limits(), .translate() on instances — are in the project unit.
  • Inserted parts are built in their own unit and scaled into the assembly automatically. An inch part inserted into a millimetre project is 25.4× larger in assembly space, as it should be.
  • Parameter overrides go to the part, so they are in the part's unit: insert(def, { width: 10 }) on an inch part means 10 in whatever the project unit is.

Sub-assemblies inside one project share the project unit, so nothing is scaled between them.

Import and export​

load() needs no unit. Imported STEP files are converted to millimetres when the import is cached (STEP carries units), and load() scales that cache into the loading file's unit — factor 1 in a millimetre file.

load("bracket");                       // scaled into this file's unit
load("bracket", { unit: 'in' });       // assertion: this asset is in inches

The { unit } option is an assertion for assets with no trustworthy metadata — a .brep copied into imports/ by hand, a STEP whose header is wrong. It overrides whatever the import recorded; leave it out otherwise.

  • STEP export writes physically correct files whatever the document unit; the receiving tool sees a 2 in boss as 2 in.
  • STL export is unitless, and slicers assume millimetres, so STL is scaled to mm by default. An export option keeps document units instead when the consumer expects them.
  • BRep is written as-is.

Precision envelope​

The kernel's tolerances are absolute, so the unit you choose sets how fine a feature it can resolve. Pick the unit that matches your feature scale:

  • Sub-millimetre detail in a metre document loses precision; model a small part in mm, not as 0.0004 of a metre.
  • Very large models in mm are fine well past the size of anything you can print or machine.

cm, m and ft exist for models that are naturally that size — furniture, buildings, plots — not as a way to write fewer digits.

tip

When in doubt, stay in mm and use inch() for the odd imperial dimension. It keeps every project in the unit the tutorials, the tolerances and the 3D-printing ecosystem assume.