Profiles & Settings
Cura uses a stacked profile system. A schematic overview of this can be seen in the image below.
Each of the entries in the stack (eg; User, Quality, Material, etc) describes a profile. When we want to find out how much infill percentage should be used ("infill_sparse_density"), we simply ask the extruder stack what value it has. The extruder stack will then ask each of the profiles that it has (in sequence) if they have a value for the requested setting. The first profile to give an answer will define what the result is.
A slightly more complicated situation occurs when the value of a setting is defined by a function. Let's take the following example into consideration. We have a setting "foo" which value is defined by the formula "=bar / 2". This is defined in the quality profile of the left extruder. The value of "bar" is defined in the material only and is set to 50.
When we ask for the value of "foo", we expect to get 25 as a result. The following calls will be made in order:
- extruder_stack.getProperty("foo", "value")
- user.getProperty("foo", "value") -> Returns None
- quality_changes.getProperty("foo", "value") -> Returns None
- intent.getProperty("foo", "value") -> Returns None
- quality.getProperty("foo", "value") -> Returns "=bar/2"
- user.getProperty("bar", "value") -> returns None
- quality_changes.getProperty("bar", "value) -> Returns None
- intent.getProperty("bar", "value) -> Returns None
- quality.getProperty("bar", "value) -> Returns None
- material.getProperty("bar", "value) -> Returns 50
The profiles have some interdependency with one other, as can be seen in the picture below.
The user settings are all changes that are not stored to any profile. In the interface, a circular reset icon is shown for each of these settings. They are completely independant of the quality, quality_changes or intent. They are only "tied" to a machine.
Quality changes contain the settings that the user changed and stored to a profile. As such, a single profile generated by a user contains at least 2 files (one quality_change for the extruder and one for the global stack). The quality changes are only tied to the quality_type, since they describe a "delta" to be applied over a quality. So even if a quality changes because a material changes, the quality changes profile could stay the same (since it's only link, the quality_type remained the same)
Intent profiles contain settings that modify the quality by giving them an intent (eg: "Engineering" or "Smooth").). These profiles depend on the material, variant and quality_type
Quality profiles hold the resolution of the print by setting the layer height. Since all extruders must have the same layer height, this value is set in the global_stack part of the quality.
Hold all the settings as defined by the active material.
The variant, in case of the extruder, hold settings that have to do with nozzle size or specific settings that relate to this.
If a user makes changes to a certain machine, but not to such a degree that it should be considered an entirely new type of machines, the settings are stored here.
The machine default settings.
All of this logic is handled by a number of classes. This section will explain how these work together. Make sure that you understand the previous sections before continuing on with this. If you're not planning to write python code / create custom plugins, it's likely that you won't need to read this.
A ContainerStack is the basic "stack" concept. As the name implies, it's a stack of containers (InstanceContainer, DefinitionContainer, etc). As a rule of thumb, the bottom container in the stack is a DefinitionContainer and the stacks above it are InstanceContainers. This ensures that if no InstanceContainer overrides a value that the default value as set by the definition is used.
The ExtruderStack is a specialized ContainerStack that represents a single extruder. It always has a GlobalStack set as it's next stack.
The GlobalStack is a specialized Containerstack that represents the basic / global settings of a machine / printer. Because it represents the global defaults of a machine, it does not have a material set.
An InstanceContainer is an unsorted set of SettingInstance objects that together form a profile. Looking at the image at the top of the page, you can see a number of InstanceContainer. "User", "quality_changes", etc; All of these are InstanceContainers. These will be serialized (stored) to .inst.cfg files. Instance containers can only change the "value" of a given SettingInstance!
A DefinitionContainer is an unsorted set of SettingDefinition objects that together form the definition of an extruder or a printer. In order to define a single 3D printer, you will need two of these profiles (one to be used in the ExtruderStack and one to be used in the GlobalStack). Note that settings that are defined in the DefinitionContainer of an extruder should not be defined in the global DefinitionContainer; If the value of a property is asked of the ExtruderStack and it exists in it's SettingDefinition, it will never continue asking the next stack. Definition containers are serialized (stored) to .def.json files. More information about the file format can be found here.
The SettingDefinition defines a single setting (for example: "layer_height") with all its properties ("value", "min_value_warning", "label", etc). The SettingDefinition must always be inside a DefinitionContainer. The SettingDefinition class contains a concept of "supported properties". These are the properties that are supported when serializing or deserializing a setting. Each property can be any of the following types: "Any", "String", "TranslatedString" and "Function"
The SettingInstance keeps track of the (changed) state of a single setting (for example: "layer_height") and must be inside an InstanceContainer. In order to keep track of the state, it needs to know what SettingDefinition it is matched with. When the value of a SettingInstance is changed, it will also notify SettingInstances that have formulas that rely on it's value.
If there are two known settings ("foo" with the value "=bar/2" and "bar" with the value "25") and the value of "bar" is changed to be 50, a signal is emitted that the value of "bar" is changed, but a signal is also emitted that the value of "foo" is changed since it's value depends on the value of bar.
It's also possible for 3D models to have specific setting overrides set per model. Only settings that have the property "settable_per_mesh" set to true can be modified in this way. Each CuraSceneNode will automatically have a ContainerStack, which only contains a single InstanceContainer, created for it. It can be accessed by calling node.callDecoration("getStack")