Interface ScopeDataUtils
ScopeData contains device properties in "DeviceLabel-PropertyName" format with String values. This class provides methods to validate that all properties exist in the current hardware configuration and to apply the properties to restore hardware state.
Access this utility via Studio.acquisitions().scopeData().
Example usage:
ScopeDataUtils utils = studio.acquisitions().scopeData();
PropertyMap scopeData = image.getMetadata().getScopeData();
// Validate first
ScopeDataUtils.ValidationResult validation = utils.validateScopeData(core, scopeData);
if (!validation.isFullyValid()) {
ReportingUtils.logMessage("Issues: " + validation.getSummary());
}
// Apply with default options
ScopeDataUtils.ApplyResult result = utils.applyScopeData(scopeData);
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interfaceOptions for controlling how ScopeData is applied to hardware.static interfaceResult of applying ScopeData to hardware.static interfaceRepresents a property change with both previous and new values.static interfaceRepresents a single property entry from ScopeData.static interfaceRepresents a property that failed to apply with error information.static interfaceResult of validating ScopeData against current hardware configuration. -
Method Summary
Modifier and TypeMethodDescriptionapplyScopeData(PropertyMap scopeData) Applies ScopeData to hardware with default options.applyScopeData(PropertyMap scopeData, ScopeDataUtils.ApplyOptions options) Applies ScopeData to hardware with configurable options.configurationToPropertyMap(mmcorej.Configuration config) Converts a Configuration (from core.getSystemStateCache()) to a PropertyMap in the standard ScopeData format ("DeviceLabel-PropertyName" keys).filterChangedProperties(mmcorej.CMMCore core, PropertyMap scopeData) Filters ScopeData to only include properties that exist in the current hardware configuration and have different values from the current state.filterReadOnlyProperties(mmcorej.CMMCore core, PropertyMap scopeData) Filters ScopeData to remove read-only properties.filterStateProperties(PropertyMap scopeData) Filters ScopeData to remove "State" properties when the device also has a "Label" property.getChangedProperties(mmcorej.CMMCore core, PropertyMap scopeData) Filters ScopeData to only include properties that exist in the current hardware configuration and have different values, returning detailed information about each property difference.String[]Parses a ScopeData key into device and property name.validateScopeData(mmcorej.CMMCore core, PropertyMap scopeData) Validates that all properties in ScopeData exist in current hardware configuration.
-
Method Details
-
parseKey
-
configurationToPropertyMap
Converts a Configuration (from core.getSystemStateCache()) to a PropertyMap in the standard ScopeData format ("DeviceLabel-PropertyName" keys).- Parameters:
config- Configuration object from CMMCore- Returns:
- PropertyMap with device properties
-
validateScopeData
Validates that all properties in ScopeData exist in current hardware configuration.- Parameters:
core- The CMMCore instancescopeData- PropertyMap containing device properties- Returns:
- ValidationResult with categorized properties
-
filterChangedProperties
Filters ScopeData to only include properties that exist in the current hardware configuration and have different values from the current state.This is useful for determining what would actually change if the ScopeData were applied, without actually applying it.
- Parameters:
core- The CMMCore instancescopeData- PropertyMap containing device properties- Returns:
- PropertyMap containing only properties that exist and differ from current values
-
getChangedProperties
List<ScopeDataUtils.PropertyChange> getChangedProperties(mmcorej.CMMCore core, PropertyMap scopeData) Filters ScopeData to only include properties that exist in the current hardware configuration and have different values, returning detailed information about each property difference.- Parameters:
core- The CMMCore instancescopeData- PropertyMap containing device properties- Returns:
- List of PropertyChange objects describing each difference
-
filterReadOnlyProperties
Filters ScopeData to remove read-only properties.Returns a new PropertyMap containing only properties that are writable. Properties for devices that don't exist in the current configuration are also removed.
- Parameters:
core- The CMMCore instancescopeData- PropertyMap containing device properties- Returns:
- PropertyMap containing only writable properties
-
filterStateProperties
Filters ScopeData to remove "State" properties when the device also has a "Label" property.State devices (like filter wheels, objectives, etc.) typically have both a numeric "State" property and a human-readable "Label" property. When both are present in the ScopeData, it's preferable to use "Label" since it's more meaningful and less error-prone if the state device configuration has changed.
- Parameters:
scopeData- PropertyMap containing device properties- Returns:
- PropertyMap with redundant State properties removed
-
applyScopeData
Applies ScopeData to hardware with default options.- Parameters:
scopeData- PropertyMap containing device properties- Returns:
- ApplyResult with details of what was applied
-
applyScopeData
ScopeDataUtils.ApplyResult applyScopeData(PropertyMap scopeData, ScopeDataUtils.ApplyOptions options) Applies ScopeData to hardware with configurable options.- Parameters:
scopeData- PropertyMap containing device propertiesoptions- Options controlling apply behavior- Returns:
- ApplyResult with details of what was applied
-