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.