org.micromanager.acquisition

Interface ScopeDataUtils

public interface ScopeDataUtils

Utility functions for validating and applying ScopeData (PropertyMap from image metadata) to hardware.

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 Classes

Modifier and Type	Interface and Description
static interface	ScopeDataUtils.ApplyOptions Options for controlling how ScopeData is applied to hardware.
static interface	ScopeDataUtils.ApplyResult Result of applying ScopeData to hardware.
static interface	ScopeDataUtils.PropertyChange Represents a property change with both previous and new values.
static interface	ScopeDataUtils.PropertyEntry Represents a single property entry from ScopeData.
static interface	ScopeDataUtils.PropertyError Represents a property that failed to apply with error information.
static interface	ScopeDataUtils.ValidationResult Result of validating ScopeData against current hardware configuration.

Method Summary

Modifier and Type	Method and Description
ScopeDataUtils.ApplyResult	applyScopeData(PropertyMap scopeData) Applies ScopeData to hardware with default options.
ScopeDataUtils.ApplyResult	applyScopeData(PropertyMap scopeData, ScopeDataUtils.ApplyOptions options) Applies ScopeData to hardware with configurable options.
PropertyMap	configurationToPropertyMap(mmcorej.Configuration config) Converts a Configuration (from core.getSystemStateCache()) to a PropertyMap in the standard ScopeData format ("DeviceLabel-PropertyName" keys).
PropertyMap	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.
PropertyMap	filterReadOnlyProperties(mmcorej.CMMCore core, PropertyMap scopeData) Filters ScopeData to remove read-only properties.
PropertyMap	filterStateProperties(PropertyMap scopeData) Filters ScopeData to remove "State" properties when the device also has a "Label" property.
java.util.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.
java.lang.String[]	parseKey(java.lang.String key) Parses a ScopeData key into device and property name.
ScopeDataUtils.ValidationResult	validateScopeData(mmcorej.CMMCore core, PropertyMap scopeData) Validates that all properties in ScopeData exist in current hardware configuration.

Method Detail

parseKey

java.lang.String[] parseKey(java.lang.String key)

Parses a ScopeData key into device and property name.

Parameters:

key - Key in "DeviceLabel-PropertyName" format

Returns:

String array with [device, property], or null if invalid format

configurationToPropertyMap

PropertyMap configurationToPropertyMap(mmcorej.Configuration config)

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

ScopeDataUtils.ValidationResult validateScopeData(mmcorej.CMMCore core,
                                                  PropertyMap scopeData)

Validates that all properties in ScopeData exist in current hardware configuration.

Parameters:

core - The CMMCore instance

scopeData - PropertyMap containing device properties

Returns:

ValidationResult with categorized properties

filterChangedProperties

PropertyMap 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.

This is useful for determining what would actually change if the ScopeData were applied, without actually applying it.

Parameters:

core - The CMMCore instance

scopeData - PropertyMap containing device properties

Returns:

PropertyMap containing only properties that exist and differ from current values

getChangedProperties

java.util.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 instance

scopeData - PropertyMap containing device properties

Returns:

List of PropertyChange objects describing each difference

filterReadOnlyProperties

PropertyMap filterReadOnlyProperties(mmcorej.CMMCore core,
                                     PropertyMap scopeData)

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 instance

scopeData - PropertyMap containing device properties

Returns:

PropertyMap containing only writable properties

filterStateProperties

PropertyMap filterStateProperties(PropertyMap scopeData)

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

ScopeDataUtils.ApplyResult applyScopeData(PropertyMap scopeData)

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 properties

options - Options controlling apply behavior

Returns:

ApplyResult with details of what was applied