From FreeCAD Documentation
Revision as of 00:13, 6 December 2013 by Jriegel (talk | contribs) (Python scripting)
Jump to: navigation, search

The Quantity is a combination of a floating point number and an Unit. It is used throughout all of FreeCAD to handle parameters and all other kind of input/output.


In a CAD or CAE system its very important to keep track on the unit of an value. Lot of trouble can arise when mixing up units or calculating results in different unit systems. One famous disaster is the crash of the Mars Climate Orbiter through out a unit mix-up. Even in the same unit-system the units come in lots of different flavors always tailored to the field of use. Simple examples are e.g. velocity in km/h (cars), m/s (robotics) or mm/minute (milling). A CAD system have to keep reliably track of units. Also it has to calculate with them and check on the right unit for special parameters.

For that reason the FreeCAD Quantity framework was created. It includes all the code and objects to deal with units, unit calculations, user input, conversion in other unit systems and the pretty output of units and values. In the long run no parameter in FreeCAD should be just a number.

All physical units can be expressed as a combination of the seven SI-Units:


An easy way to express a Unit is a integer array of size 7 (number of base units) that defines what the unit is. The signature of the 7 base units are:

  • LENGTH: [1,0,0,0,0,0,0]
  • MASS: [0,1,0,0,0,0,0]
  • TIME: [0,0,1,0,0,0,0]
  • ELECTRIC CURRENT: [0,0,0,1,0,0,0]
  • AMOUNT OF SUBSTANCE: [0,0,0,0,0,1,0]
  • LUMINOUS INTENSITY: [0,0,0,0,0,0,1]


  • MASS DENSITY: [-3,1,0,0,0,0,0]
  • AREA: [0,2,0,0,0,0,0]

Since angle is physically dimensionless, but never the less important to a CAD system we add one more virtual unit for Angle. This makes a vector of 8 in the FreeCAD unit signature.

Units calculator

Often you are in need of calculating units from one system to another. For example you have old parameter tables with wired units. In that cases FreeCAD offers a conversion tool called Units-Calculator which helps in translating units.

Its description in detail is here: Std_UnitsCalculator

Python scripting

The Unit and Quantity system in FreeCAD is (as nearly everything) fully accessibly via Python.


The Unit class represents the Fingerprint of any physical unit. As descriped in the Basics section a vector of 8 numbers is used to represent this fingerprint. The Unit class allows the handling and calculation with this information.

from Units import Unit

# creating a Unit with certain signature
Unit(0,1)      # Mass     (kg)
Unit(1)        # Length   (mm)
Unit(-1,1,-2)  # Pressure (kg/mm*s^2)

# using predefined constats

# parsing unit out of an string
Unit('kg/(m*s^2)')    # Pressure
Unit('Pa')            # the same as combined Unit Pascale
Unit('J')             # Joul (Work,Energy) mm^2*kg/(s^2)

# you can use units from all supported unit-systems
Unit('psi')           # Imperial pressure
Unit('lb')            # Mass
Unit('ft^2')          # Area

# comparing units
Unit(0,1) == Unit(FreeCAD.Units.Mass)

# getting type of unit
Unit('kg/(m*s^2)').Type == 'Pressure'

# calculating
Unit('kg') * Unit('m^-1*s^-2') == Unit('kg/(m*s^2)')

The Unit is mainly used to descripe a certain unit-type for a parameter. There fore a special Property Type in FreeCAD can transport a Unit to check and ensure the right Unit. A Unit and a float value is called Quantity.


from Units import Unit,Quantity

# to create a quantity you need a value (float) and a Unit
Quantity(1.0,Unit(0,1))               # Mass      1.0 kg
Quantity(1.0,Unit(1))                 # Length    1.0 mm
Quantity(1.0,Unit(-1,1,-2))           # Pressure  1.0 kg/mm*s^2
Quantity(1.0,FreeCAD.Units.Pressure)  # Pressure  1.0 kg/mm*s^2

# you can directly give a signature
Quantity(1.0,0,1)      # Mass      1.0 kg
Quantity(1.0,1)        # Length    1.0 mm
Quantity(1.0,-1,1,-2)  # Pressure  1.0 kg/mm*s^2

# parsing Quantitis out of an string
Quantity('1.0 kg/(m*s^2)')    # Pressure
Quantity('1.0 Pa')            # the same as combined Unit Pascale
Quantity('1.0 J')             # Joul (Work,Energy) mm^2*kg/(s^2)

# you can use units from all supported unit-systems
Quantity('1.0 psi')           # Imperial pressure
Quantity('1.0 lb')            # Mass
Quantity('1.0 ft^2')    

# the quantity parser can do calculations too
Quantity('360/5 deg')           # splitting circle 
Quantity('1/16 in')             # fractions
Quantity('5.3*6.3 m^2')         # calculating an area
Quantity('1/(log(2.3)/sin(pi)*3.4)+1.8e-3 m')
Quantity('1fo 3in')             # imperial style


Parser supported Units

Although all physical units can be described with the seven SI units, most of the units used in technical areas are common combined units (like Pa = N/m^2 Pascal ). There fore the units parser in FreeCAD support lot of SI and Imperial combined units. This units are defined in src/Base/QuantityParser.l file and can be further advanced in the future.

"nm"   = Quantity(1.0e-6    ,Unit(1));           // nano meter
"ym"   = Quantity(1.0e-3    ,Unit(1));           // micro meter
"mm"   = Quantity(1.0       ,Unit(1));           // milli meter
"cm"   = Quantity(10.0      ,Unit(1));           // centi meter
"dm"   = Quantity(100.0     ,Unit(1));           // deci meter
"m"    = Quantity(1.0e3     ,Unit(1));           // meter
"km"   = Quantity(1.0e6     ,Unit(1));           // kilo meter
"l"    = Quantity(1000000.0 ,Unit(3));           // Liter      dm^3
"yg"   = Quantity(1.0e-9    ,Unit(0,1));         // milli gram
"mg"   = Quantity(1.0e-6    ,Unit(0,1));         // milli gram
"g"    = Quantity(1.0e-3    ,Unit(0,1));         // gram
"kg"   = Quantity(1.0       ,Unit(0,1));         // kilo gram
"t"    = Quantity(1000.0    ,Unit(0,1));         // ton
"s"    = Quantity(1.0       ,Unit(0,0,1));       // second                          (internal standard time)
"min"  = Quantity(60.0      ,Unit(0,0,1));       // minute
"h"    = Quantity(3600.0    ,Unit(0,0,1));       // hour  
"A"    = Quantity(1.0       ,Unit(0,0,0,1));     // Ampere          (internal standard electric current)
"mA"   = Quantity(0.001     ,Unit(0,0,0,1));     // milli Ampere         
"kA"   = Quantity(1000.0    ,Unit(0,0,0,1));     // kilo Ampere         
"MA"   = Quantity(1.0e6     ,Unit(0,0,0,1));     // Mega Ampere         
"K"    = Quantity(1.0       ,Unit(0,0,0,0,1));   // Kelvin (internal standard thermodynamic temperature)
"mK"   = Quantity(0.001     ,Unit(0,0,0,0,1));   // Kelvin         
"yK"   = Quantity(0.000001  ,Unit(0,0,0,0,1));   // Kelvin         
"mol"  = Quantity(1.0       ,Unit(0,0,0,0,0,1));   // Mole     (internal standard amount of substance)        
"cd"   = Quantity(1.0       ,Unit(0,0,0,0,0,0,1)); // Candela   (internal standard luminous intensity)        
"deg"  = Quantity(1.0           ,Unit(0,0,0,0,0,0,0,1));  // degree         (internal standard angle)
"rad"  = Quantity(180/M_PI      ,Unit(0,0,0,0,0,0,0,1));  // radian         
"gon"  = Quantity(360.0/400.0   ,Unit(0,0,0,0,0,0,0,1));  // gon         
"in"   = Quantity(25.4          ,Unit(1));       // inch
"\""   = Quantity(25.4          ,Unit(1));       // inch
"fo"   = Quantity(304.8         ,Unit(1));       // foot
"'"    = Quantity(304.8         ,Unit(1));       // foot
"th"   = Quantity(0.0254        ,Unit(1));       // thou
"yr"   = Quantity(914.4         ,Unit(1));       // yard

"lb"   = Quantity(0.45359237    ,Unit(0,1));    // pound
"oz"   = Quantity(0.0283495231  ,Unit(0,1));    // ounce
"st"   = Quantity(6.35029318    ,Unit(0,1));    // Stone
"cwt"  = Quantity(50.80234544   ,Unit(0,1));    // hundredweights
Available translations of this page: Flag-fr.jpg Flag-it.jpg