.FCSTD File Format – Property types

Numbers, text and flags

The unit types are written exactly like App::PropertyQuantity: Acceleration, AmountOfSubstance, Angle, Area, AreaMomentOfInertia, CompressiveStrength, CurrentDensity, Density, DissipationRate, Distance, DynamicViscosity, ElectricalCapacitance, ElectricalConductance, ElectricalConductivity, ElectricalInductance, ElectricalResistance, ElectricCharge, ElectricCurrent, ElectricPotential, ElectromagneticPotential, Force, Frequency, HeatFlux, InverseArea, InverseLength, InverseVolume, KinematicViscosity, Length, LuminousIntensity, MagneticFieldStrength, MagneticFlux, MagneticFluxDensity, Magnetization, Mass, MassMomentOfInertia, Moment, Power, Pressure, QuantityConstraint, ShearModulus, SpecificEnergy, SpecificHeat, Speed, Stiffness, StiffnessDensity, Stress, SurfaceChargeDensity, Temperature, ThermalConductivity, ThermalExpansionCoefficient, ThermalTransferCoefficient, Time, UltimateTensileStrength, VacuumPermittivity, Velocity, Volume, VolumeChargeDensity, VolumeFlowRate, VolumetricThermalExpansionCoefficient, Work, YieldStrength and YoungsModulus, each prefixed App::Property.

Lists and sets

The layouts of the binary entries are on the archive page. In XML-only output a FloatList is written inline, as FloatList count with one F v child per value.

Vectors, placements and colours

For files whose ProgramVersion is older than FreeCAD 1.1, the reader inverts the alpha of colours, because the meaning of alpha changed in 1.1.

Links

Link properties refer to objects by internal name. The Child, Global and Hidden variants of each link type differ only in scope and write the same element.

Sub-element names, such as Edge3 or Face1, can have two forms: an old-style name and a topological (mapped) name. The Sub element’s value, and the sub attribute of Link and XLink, hold the old-style name when there is one, for older FreeCAD versions to read, and extra attributes carry the rest:

Expressions and Python objects

No Python code is stored: only the state, so the class must be available when the file is opened. The reader also accepts a Python element with a file attribute or an unencoded value.

Embedded files

While the document is open, the file lives in the document’s transient folder and is made read-only after reading.

Part shapes

Part::PropertyPartShape, the Shape of Part and PartDesign objects, writes a Part element, then optionally the shape’s string table and element map.

The element map and string table are written only when the ElementMap version is not empty or SaveHasher is set. Other Part properties: Part::PropertyFilletEdges writes FilletEdges file (binary entry), and Part::PropertyShapeHistory and Part::PropertyShapeCache write nothing, leaving the Property element empty.

Meshes

Sketch geometry

Part::PropertyGeometryList, the Geometry of a sketch, writes GeometryList count with one Geometry element per curve. Geometry has a type attribute (the C++ type, e.g. Part::GeomLineSegment) and migrated="1"; inside it, GeoExtensions count holds the curve’s saved extensions, and then the curve element:

CenterX/Y/Z stands for the three attributes CenterX, CenterY and CenterZ, and likewise for Normal. AngleXU turns the curve within its plane, measured from a reference axis system the code builds from the centre and normal; StartAngle and EndAngle are the trimmed curve’s first and last parameters. A trimmed curve of another kind cannot be saved (GeomTrimmedCurve throws “not implemented”).

Sketch constraints

Sketcher::PropertyConstraintList writes ConstraintList count with one Constrain element (spelt without the final t) per constraint.

Point positions: 0 the edge itself (no point), 1 start point, 2 end point, 3 mid point (centre).

Worked example

Property elements from the FreeCAD wiki’s example Document.xml (the whole file is on the document page):

<Property name="Height" type="App::PropertyLength">
   <Float value="10"/>
</Property>
<Property name="Label" type="App::PropertyString">
   <String value="Box2"/>
</Property>
<Property name="Placement" type="App::PropertyPlacement">
   <PropertyPlacement Px="0" Py="0" Pz="0" Q0="0" Q1="0" Q2="0" Q3="1"/>
</Property>
<Property name="Pos" type="App::PropertyPlacementLink">
   <Link value=""/>
</Property>
<Property name="Shape" type="Part::PropertyPartShape">
   <Part file="PartShape.brp2"/>
</Property>

App::PropertyLength is a unit type, so it writes a plain Float. The placement has only the quaternion, so the reader builds the rotation from Q0–Q3: the identity, since the scalar part Q3 is 1. App::PropertyPlacementLink is a link type and writes Link; its empty value means no link. A current FreeCAD would also write the A, Ox, Oy and Oz attributes on the placement and an ElementMap attribute on Part, and would name the shape entry after the object and property.

Not confirmed

• The character order of BoolList (which end is item 0): it follows Boost’s dynamic bitset conversion, which was not read.
• The units in which unit types store their numbers: only the number is written, and FreeCAD’s internal unit for each quantity was not read.
• The axis written in Ox, Oy and Oz for a rotation of zero angle.
• The sketch geometry extensions inside GeoExtensions (such as construction and internal geometry flags), the attributes written by GeometryMigrationPersistenceExtension on Geometry, and the saved forms of surface geometry types.
• Properties defined only by other workbenches (TechDraw, FEM, CAM, BIM and so on) beyond the types above.
• Whether the XLink file path is stored relative to the linking document in a normal save.

Sources

• Property – FreeCAD wiki, the list of property types, read from the FreeCAD-documentation repository
• File Format FCStd – FreeCAD wiki, the example Document.xml
• Scripted objects – FreeCAD wiki: files never carry Python code
• FreeCAD source code – main branch: src/App/PropertyStandard.cpp, PropertyUnits.cpp, PropertyGeo.cpp, PropertyLinks.cpp, PropertyExpressionEngine.cpp, PropertyPythonObject.cpp, PropertyFile.cpp, src/Base/Rotation.cpp, src/Base/Color.h, src/Mod/Part/App/PropertyTopoShape.cpp, PropertyGeometryList.cpp and Geometry.cpp, src/App/ComplexGeoData.cpp, src/Mod/Mesh/App/MeshProperties.cpp, src/Mod/Sketcher/App/PropertyConstraintList.cpp, Constraint.cpp, Constraint.h and GeoEnum.h