Model Classes

Motivation

Encapsulate values and persistence of user-configurable properties for parts.

Model classes act as extensions to Part Classes, for when you want dynamic geometry, or parameteric properties the user can manipulate in FreeCAD’s GUI within the Property Editor after the part is made.

For example, extending our Box part class to make the length and width editable by the user:

from example.app.part import Box


class BoxModel:

    def __init__(self, obj):
        self.Type = 'Box'

        obj.Proxy = self

        obj.addProperty('App::PropertyLength', 'Length',
                        'Dimensions', 'Box length').Length = 10.0
        obj.addProperty('App::PropertyLength', 'Width',
                        'Dimensions', 'Box width').Width = 10.0

    def execute(self, obj):
        obj.Shape = Box.make(obj.Length, obj.Width)

The constructor or __init__ method initializes the parameteric properties, and the execute method handles the construction of the geometry.

Colloquially known in the FreeCAD community as FeaturePython Objects or Scripted Objects, we choose the name “model” as we believe the terms “feature python object” or “scripted object” are not accurate enough and are potentially misleading.

Additionally, model classes handle serialization, or saving and restoring data through App::Property objects. This is a similar role to what some frameworks call a Data Transfer Object (DTO).

Model objects are saved in FreeCAD .FcStd files with Python’s json module.

The json module transforms the model object into JSON (a string with a special format) for persisting the object to disk. Upon loading FreeCAD, the json module uses that string to recreate the original object, provided it has access to the source code that created the object.

Important

This means users need to have the workbench installed in order to open any FCStd files with model classes saved in them.

Another motivation for the separation of part classes from model classes is to keep the “shape” separate from the persistence of dynamic properties to disk.

Sometimes, you don’t want to force users to install a workbench in order to open FCStd files with particular parts in them.

Therfore, converting a model to a “shape” using a part class can be useful.

Hint

The platform may standardize a to_shape() method on model classes for this purpose in the future.

For additional information, see the FreeCAD Wiki on FeaturePython Objects and Scripted Objects.