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);
  • Method Details

    • parseKey

      String[] parseKey(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

      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

      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