Interface DataManager


public interface DataManager
This class provides general utility functions for working with Micro-Manager data. You can access it via ScriptInterface's data() method (for example, "mm.data().cordsBuilder()").
  • Method Details

    • coordsBuilder

      Coords.Builder coordsBuilder()
      Generate a "blank" CoordsBuilder for use in constructing new Coords instances.
      Returns:
      a CoordsBuilder used to construct new Coords instances.
    • getCoordsBuilder

      @Deprecated Coords.Builder getCoordsBuilder()
      Deprecated.
      Use coordsBuilder() instead
      Generate a "blank" CoordsBuilder for use in constructing new Coords instances.
      Returns:
      a CoordsBuilder used to construct new Coords instances.
    • createCoords

      Deprecated.
      use of Strings for Coords is discouraged
      Generate a Coords object from the provided normalized coordinate string. Coordinate strings are comma-delimited strings of axis/position pairs separated by equals signs. Case matters, but whitespace is ignored. Positions must be integers. For example, "z=8" or "time = 5, channel = 2", but not "stagePosition = 1.5" because the position is not an integer. For this method, it is acceptable to use the shorthand axis names Coords.CHANNEL_SHORT, Coords.TIME_SHORT, and Coords.STAGE_POSITION_SHORT, for example "t=4,p=8,c=0,z=5". If you are using custom axes, be aware that axis names must start with an alphabetical character, and may otherwise contain alphanumerics and underscores. For example, "filter2_pos" is a valid axis, but "1filter-pos" is not, because it starts with a number, and because it contains a "-" which is not a legal character.
      Parameters:
      def - Normalized coordinate definition string.
      Returns:
      Coords generated based on the definition string.
      Throws:
      IllegalArgumentException - if the definition string is malformatted.
    • createRAMDatastore

      Datastore createRAMDatastore()
      Generate a new, "blank" Datastore with RAM-based Storage and return it. This Datastore will not be managed by Micro-Manager by default (see the org.micromanager.api.display.DisplayManager.manage() method for more information).
      Returns:
      an empty RAM-based Datastore.
    • createRAMDatastore

      Datastore createRAMDatastore(Datastore storeToCopy)
    • createRewritableRAMDatastore

      RewritableDatastore createRewritableRAMDatastore()
      Generate a new, "blank" RewritableDatastore with RAM-based Storage and return it. This Datastore will not be managed by Micro-Manager by default (see the org.micromanager.api.display.DisplayManager.manage() method for more information).
      Returns:
      an empty RAM-based RewritableDatastore.
    • createRewritableRAMDatastore

      RewritableDatastore createRewritableRAMDatastore(Datastore storeToCopy)
    • createNDTIFFDatastore

      Datastore createNDTIFFDatastore(String directory) throws IOException
      Generate a new, "blank" Datastore with NDTIFF-based Storage and return it. This format stores multiple 2D image planes in the same file, up to 4GB per file. This Datastore will not be managed by Micro-Manager by default (see the org.micromanager.api.display.DisplayManager.manage() method for more information). Be certain to call the freeze() method of the Datastore when you have finished adding data to it, as the Storage must finalize the dataset before it is properly saved to disk.

      More information on the NDTiff format can be found at: https://github.com/micro-manager/NDTiffStorage

      Parameters:
      directory - Location on disk to store the file(s).
      Returns:
      an empty Datastore backed by disk in the form of one or more TIFF files each containing multiple image planes.
      Throws:
      IOException - if any errors occur while opening files for writing.
    • createNDTIFFDatastore

      Datastore createNDTIFFDatastore(Datastore storeToCopy, String directory) throws IOException
      Throws:
      IOException
    • createMultipageTIFFDatastore

      Datastore createMultipageTIFFDatastore(String directory, boolean shouldGenerateSeparateMetadata, boolean shouldSplitPositions) throws IOException
      Generate a new, "blank" Datastore with multipage TIFF-based Storage and return it. This format stores multiple 2D image planes in the same file, up to 4GB per file. This Datastore will not be managed by Micro-Manager by default (see the org.micromanager.api.display.DisplayManager.manage() method for more information). Be certain to call the freeze() method of the Datastore when you have finished adding data to it, as the Storage must finalize the dataset before it is properly saved to disk.

      Please note that the multipage TIFF storage system currently only supports the time, Z, channel, and stage position axes for images. Attempts to add images with "custom" axes will create an error dialog, and the image will not be added to the Datastore.

      Parameters:
      directory - Location on disk to store the file(s).
      shouldGenerateSeparateMetadata - if true, a separate metadata.txt file will be generated.
      shouldSplitPositions - if true, then each stage position (per Coords.STAGE_POSITION) will be in a separate file.
      Returns:
      an empty Datastore backed by disk in the form of one or more TIFF files each containing multiple image planes.
      Throws:
      IOException - if any errors occur while opening files for writing.
    • createMultipageTIFFDatastore

      Datastore createMultipageTIFFDatastore(Datastore storeToCopy, String directory, boolean shouldGenerateSeparateMetadata, boolean shouldSplitPositions) throws IOException
      Throws:
      IOException
    • createSinglePlaneTIFFSeriesDatastore

      Datastore createSinglePlaneTIFFSeriesDatastore(String directory) throws IOException
      Generate a new, "blank" Datastore whose Storage is a series of single-plane TIFF files. This Datastore will not be managed by Micro-Manager by default (see the org.micromanager.api.display.DisplayManager.manage() method for more information). Be certain to call the freeze() method of the Datastore when you have finished adding data to it, as the Storage must finalize the dataset before it is properly saved to disk.

      Please note that the single-plane TIFF series storage system currently only supports the time, Z, channel, and stage position axes for images. Attempts to add images with "custom" axes will create an error dialog, and the image will not be added to the Datastore.

      Parameters:
      directory - Location on disk to store the files.
      Returns:
      an empty Datastore backed by disk in the form of multiple single-plane TIFF files.
      Throws:
      IOException - If the directory already exists.
    • createSinglePlaneTIFFSeriesDatastore

      Datastore createSinglePlaneTIFFSeriesDatastore(Datastore storeToCopy, String directory) throws IOException
      Throws:
      IOException
    • getUniqueSaveDirectory

      String getUniqueSaveDirectory(String path)
      Given a path string, create a unique string with that name. In short, when creating a disk-backed datastore, you should use this method to calculate the save path, to ensure that you do not accidentally overwrite existing data. For example, if you want to repeatedly save datasets under "C:\AcquisitionData\beads", then you can pass "C:\AcquisitionData\beads" to this function, and you will get out, in order: - C:\AcquisitionData\beads - C:\AcquisitionData\beads_2 - C:\AcquisitionData\beads_3 - ... Micro-Manager will look at the contents of the directory, and append numerical suffixes as needed to ensure that no data gets overwritten. The path returned by this function will always be 1 greater than the largest suffix currently in use.
      Parameters:
      path - String used to create a unique name
      Returns:
      String to a unique directory to be used to save data
    • promptForDataToLoad

      Datastore promptForDataToLoad(Window parent, boolean isVirtual) throws IOException
      Display a dialog prompting the user to select a location on disk, and invoke loadData() on that selection. If you then want that data to be displayed in an image display window, use the DisplayManager.createDisplay() method or the DisplayManager.loadDisplays() method.
      Parameters:
      parent - Window to show the dialog on top of. May be null.
      isVirtual - if true, then only the data required will be loaded from disk; otherwise the entire dataset will be loaded. See note on loadData.
      Returns:
      The Datastore generated by loadData(), or null if the user cancels the dialog or there is insufficient memory to open the data.
      Throws:
      IOException - if loadData() encountered difficulties.
    • loadData

      Datastore loadData(String directory, boolean isVirtual) throws IOException
      Load the image data at the specified location on disk, and return a Datastore for that data. This Datastore will not be managed by Micro-Manager by default (see the org.micromanager.api.display.DisplayManager.manage() method for more information).
      Parameters:
      directory - Location on disk from which to pull image data.
      isVirtual - If true, then only load images into RAM as they are requested. This reduces RAM utilization and has a lesser delay at the start of image viewing, but has worse performance if the entire dataset needs to be viewed or manipulated.
      Returns:
      A Datastore backed by appropriate Storage that provides access to the images.
      Throws:
      IOException - if there was any error in reading the data.
    • loadData

      Datastore loadData(Component parent, String directory, boolean isVirtual) throws IOException
      Load the image data at the specified location on disk, and return a Datastore for that data. This Datastore will not be managed by Micro-Manager by default (see the org.micromanager.api.display.DisplayManager.manage() method for more information).
      Parameters:
      parent - GUI object over which to place progress indicators When null, center of the screen will be used
      directory - Location on disk from which to pull image data.
      isVirtual - If true, then only load images into RAM as they are requested. This reduces RAM utilization and has a lesser delay at the start of image viewing, but has worse performance if the entire dataset needs to be viewed or manipulated.
      Returns:
      A Datastore backed by appropriate Storage that provides access to the images.
      Throws:
      IOException - if there was any error in reading the data.
    • getPreferredSaveMode

      Datastore.SaveMode getPreferredSaveMode()
      Return the save mode that the user prefers to use. This is automatically updated whenever the user saves a file.
      Returns:
      save mode that the user prefers to use
    • createImage

      Image createImage(Object pixels, int width, int height, int bytesPerPixel, int numComponents, Coords coords, Metadata metadata)
      Generate a new Image with the provided pixel data, rules for interpreting that pixel data, coordinates, and metadata. Pixel data will be copied.
      Parameters:
      pixels - A byte[], short[], int[], or float[] array of pixel data. This array will be copied, so changes in this array will not be propagated to the Image
      width - Width of the image, in pixels
      height - Height of the image, in pixels
      bytesPerPixel - How many bytes are allocated to each pixel in the image. Currently only 1, 2, and 4-byte images are supported.
      numComponents - How many colors are encoded into each pixel. Currently only 1-component (grayscale) and 3-component (RGB) images are supported.
      coords - Coordinates defining the position of the Image within a larger dataset.
      metadata - Image metadata.
      Returns:
      A new Image based on the input parameters.
      Throws:
      IllegalArgumentException - if the pixels array has length less than width * height.
    • wrapImage

      Image wrapImage(Object pixels, int width, int height, int bytesPerPixel, int numComponents, Coords coords, Metadata metadata)
      Generate a new Image with the provided pixel data, rules for interpreting that pixel data, coordinates, and metadata. Pixel data will be used without copying, so later changes to the pixel data will result in changes to this image
      Parameters:
      pixels - A byte[] or short[] array of unsigned pixel data. This array will be used as provided, so changes in pixel values will result in changes to this image
      width - Width of the image, in pixels
      height - Height of the image, in pixels
      bytesPerPixel - How many bytes are allocated to each pixel in the image. Currently only 1, 2, and 4-byte images are supported.
      numComponents - How many colors are encoded into each pixel. Currently only 1-component (grayscale) and 3-component (RGB) images are supported.
      coords - Coordinates defining the position of the Image within a larger dataset.
      metadata - Image metadata.
      Returns:
      A new Image based on the input parameters.
      Throws:
      IllegalArgumentException - if the pixels array has length less than width * height.
    • convertTaggedImage

      Image convertTaggedImage(mmcorej.TaggedImage tagged) throws mmcorej.org.json.JSONException, IllegalArgumentException
      Given a TaggedImage input, output an Image based on the TaggedImage. Note that certain properties in the metadata in the TaggedImage's tags will be converted into the scopeData and userData PropertyMaps of the Metadata, based on the assumption that the TaggedImage was generated by the hardware that this instance of Micro-Manager is controlling. If you do not want this to happen, you will need to call the version of convertTaggedImage() that takes a Coords and Metadata parameter.

      PixelData of the tagged image may be used directly (i.e. without copying), so it is unsafe to make changes to tagged.pix after calling this function.

      Parameters:
      tagged - TaggedImage to be converted
      Returns:
      An Image based on the TaggedImage
      Throws:
      mmcorej.org.json.JSONException - if the TaggedImage's metadata cannot be read
      IllegalArgumentException - if portions of the TaggedImage's metadata are malformed.
    • convertTaggedImage

      Image convertTaggedImage(mmcorej.TaggedImage tagged, Coords coords, Metadata metadata) throws mmcorej.org.json.JSONException, IllegalArgumentException
      Given a TaggedImage input, output an Image based on the TaggedImage, but with the Coords and/or Metadata optionally overridden.

      PixelData of the tagged image may be used directly (i.e. without copying), so it is unsafe to make changes to tagged.pix after calling this function.

      Parameters:
      tagged - TaggedImage to be converted
      coords - Coords at which the new image is located. If null, then the coordinate information in the TaggedImage will be used.
      metadata - Metadata for the new image. If null, then the metadata will be derived from the TaggedImage instead.
      Returns:
      An Image based on the TaggedImage
      Throws:
      mmcorej.org.json.JSONException - if the TaggedImage's metadata cannot be read
      IllegalArgumentException - if portions of the TaggedImage's metadata are malformed.
    • getMetadataBuilder

      @Deprecated Metadata.Builder getMetadataBuilder()
      Deprecated.
      Use metadataBuilder() instead
      Generate a "blank" MetadataBuilder for use in constructing new Metadata instances.
      Returns:
      a MetadataBuilder for creating new Metadata instances.
    • metadataBuilder

      Metadata.Builder metadataBuilder()
      Generate a "blank" MetadataBuilder for use in constructing new Metadata instances.
      Returns:
      a MetadataBuilder for creating new Metadata instances.
    • getSummaryMetadataBuilder

      @Deprecated SummaryMetadata.Builder getSummaryMetadataBuilder()
      Deprecated.
      Generate a "blank" SummaryMetadataBuilder for use in constructing new SummaryMetadata instances.
      Returns:
      a SummaryMetadataBuilder for creating new SummaryMetadata instances.
    • summaryMetadataBuilder

      SummaryMetadata.Builder summaryMetadataBuilder()
      Generate a "blank" SummaryMetadataBuilder for use in constructing new SummaryMetadata instances.
      Returns:
      a SummaryMetadataBuilder for creating new SummaryMetadata instances.
    • getPropertyMapBuilder

      @Deprecated PropertyMap.Builder getPropertyMapBuilder()
      Deprecated.
      Use PropertyMaps.builder() instead
      Generate a "blank" PropertyMap.Builder with all null values.
      Returns:
      a PropertyMapBuilder for creating new PropertyMap instances.
    • loadPropertyMap

      Deprecated.
      Attempt to load a file that contains PropertyMap data.
      Parameters:
      path - Path to the file to load.
      Returns:
      new PropertyMap based on data in the specified file.
      Throws:
      FileNotFoundException - if the path does not point to a file.
      IOException - if there was an error reading the file.
    • createPipeline

      Pipeline createPipeline(List<ProcessorFactory> factories, Datastore store, boolean isSynchronous)
      Create a new Pipeline using the provided list of ProcessorFactories.
      Parameters:
      factories - List of ProcessorFactories which will each be used, in order, to create a Processor for the new Pipeline.
      store - Datastore in which Images should be stored after making their way through the Pipeline.
      isSynchronous - If true, then every call to Pipeline.insertImage() will block until the input Image has been "fully consumed" by the pipeline (any result Image(s) have been added to the Datastore the Pipeline is connected to). If false, then a separate thread is created for each Processor in the Pipeline, in which that Processor's work is done, and any call to Pipeline.insertImage() will return as soon as the first processor in the pipeline begins processing the image. The output images from the pipeline will arrive in the Datastore at some indeterminate later time.
      Returns:
      a Pipeline containing Processors as specified by the input factories.
    • copyApplicationPipeline

      Pipeline copyApplicationPipeline(Datastore store, boolean isSynchronous)
      Create a copy of the current application Pipeline as configured in the "Data Processing Pipeline" window. This pipeline is used by Micro-Manager for data acquisition. Compare copyLivePipeline().
      Parameters:
      store - Datastore in which Images should be stored after making their way through the Pipeline.
      isSynchronous - If true, then every call to Pipeline.insertImage() will block until the input Image has been "fully consumed" by the pipeline (any result Image(s), if any, have been added to the Datastore the Pipeline is connected to). If false, Pipeline.insertImage() will return immediately and the Images will arrive in the Datastore at some indeterminate later time.
      Returns:
      a Pipeline based on the current GUI pipeline.
    • copyLivePipeline

      Pipeline copyLivePipeline(Datastore store, boolean isSynchronous)
      Create a copy of the current Live Pipeline as configured in the "Data Processing Pipeline" window. This pipeline is only used by Micro-Manager for the Snap/Live view. Compare copyApplicationPipeline().
      Parameters:
      store - Datastore in which Images should be stored after making their way through the Pipeline.
      isSynchronous - If true, then every call to Pipeline.insertImage() will block until the input Image has been "fully consumed" by the pipeline (any result Image(s), if any, have been added to the Datastore the Pipeline is connected to). If false, Pipeline.insertImage() will return immediately and the Images will arrive in the Datastore at some indeterminate later time.
      Returns:
      a Pipeline based on the current GUI pipeline.
    • getApplicationPipelineConfigurators

      List<ProcessorConfigurator> getApplicationPipelineConfigurators(boolean includeDisabled)
      Return a list of the ProcessorConfigurators currently being used by the application pipeline interface. If `includeDisabled` is false this only returns those configurators that are currently enabled.
      Parameters:
      includeDisabled - determines whether or not to include configurators that are not currently enabled.
      Returns:
      An ordered list of ProcessorConfigurators.
    • getLivePipelineConfigurators

      List<ProcessorConfigurator> getLivePipelineConfigurators(boolean includeDisabled)
      Return a list of the ProcessorConfigurators currently being used by the live pipeline interface. If `includeDisabled` is false this only returns those configurators that are currently enabled.
      Parameters:
      includeDisabled - determines whether or not to include configurators that are not currently enabled.
      Returns:
      An ordered list of ProcessorConfigurators.
    • clearPipeline

      void clearPipeline()
      Clear the current application pipeline, so that no on-the-fly image processing is performed.
    • addAndConfigureProcessor

      void addAndConfigureProcessor(ProcessorPlugin plugin)
      Add a new instance of the given ProcessorPlugin to the current application image processing pipeline. The pipeline configuration window will be opened if it is not already open. The new processor will be inserted onto the end of the pipeline, and the appropriate ProcessorConfigurator for that plugin will be run.
      Parameters:
      plugin - instance of a ProcessorPlugin that will be added to the current application image processing pipeline
    • addConfiguredProcessor

      void addConfiguredProcessor(ProcessorConfigurator config, ProcessorPlugin plugin)
      Add the provide ProcessorConfigurator onto the end of the application image processing pipeline.
      Parameters:
      config - The ProcessorConfigurator that is responsible for configuring this processor.
      plugin - The ProcessorPlugin that the ProcessorConfigurator came from.
    • setApplicationPipeline

      void setApplicationPipeline(List<ProcessorPlugin> plugins)
      Set the current application pipeline to be the provided list of ProcessorPlugins. The Pipeline configuration window will be opened if it is not already open, as will the ProcessorConfigurators for each of the ProcessorPlugins provided. Equivalent to calling clearPipeline() and then iteratively calling addAndConfigureProcessor().
      Parameters:
      plugins - List of ProcessorPlugins that will henceforth be used as the application's processor pipeline
    • isApplicationPipelineStepEnabled

      boolean isApplicationPipelineStepEnabled(int index)
      Checks whether or not the plugin at position `index` in the list is enabled for the application pipeline.
      Parameters:
      index - an int determining which position in the list to check
      Returns:
      boolean of whether or not the plugin is enabled.
    • setApplicationPipelineStepEnabled

      void setApplicationPipelineStepEnabled(int index, boolean enabled)
      Sets whether or not the plugin at position `index` in the list is enabled for the application pipeline.
      Parameters:
      index - an int determining which position in the list to check
      enabled - of whether or not the plugin should be enabled.
    • isLivePipelineStepEnabled

      boolean isLivePipelineStepEnabled(int index)
      Checks whether or not the plugin at position `index` in the list is enabled for the live pipeline.
      Parameters:
      index - an int determining which position in the list to check
      Returns:
      boolean of whether or not the plugin is enabled.
    • setLivePipelineStepEnabled

      void setLivePipelineStepEnabled(int index, boolean enabled)
      Sets whether or not the plugin at position `index` in the list is enabled for the live pipeline.
      Parameters:
      index - an int determining which position in the list to check
      enabled - of whether or not the plugin should be enabled.
    • notifyPipelineChanged

      void notifyPipelineChanged()
      Notify the application that the state of one of the processors in the pipeline has changed, and thus that entities that use the application pipeline should grab a new copy of it. This will cause a NewPipelineEvent event to be posted to the application event bus (which can be accessed via Studio.events()).
    • ij

      Provide access to the ImageJConverter() object.
      Returns:
      An implementation of the ImageJConverter interface.
    • getImageJConverter

      ImageJConverter getImageJConverter()
      Provide access to the ImageJConverter() object. Identical to ij() except in name.
      Returns:
      An implementation of the ImageJConverter interface.