loci.formats.in

## Class PrairieMetadata

- java.lang.Object
- - loci.formats.in.PrairieMetadata

-     public class PrairieMetadata
      extends java.lang.Object

  Metadata structure for Prairie Technologies' TIFF-based format.
  Author:
    Curtis Rueden, Michael Fox

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `PrairieMetadata.Frame` A Prairie `<Frame>`, beneath a `<Sequence>`.
    `class` | `PrairieMetadata.PFile` A Prairie `<File>` beneath a `<Frame>`.
    `class` | `PrairieMetadata.Sequence` A Prairie `<Sequence>`.
    `static interface` | `PrairieMetadata.Value` A value in a Prairie metadata dictionary.
    `static class` | `PrairieMetadata.ValueItem` A leaf value with an actual `PrairieMetadata.ValueItem.value()` as well as an optional `PrairieMetadata.ValueItem.description()`.
    `static class` | `PrairieMetadata.ValueTable` A table of values.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private java.util.HashSet<java.lang.Integer>` | `activeChannels` Set of active channel indices.
    `private PrairieMetadata.ValueTable` | `config` Key/value pairs from CFG and/or ENV files.
    `private int` | `cycleMax` Maximum cycle value.
    `private int` | `cycleMin` Minimum cycle value.
    `private java.lang.String` | `date` The date of the acquisition.
    `private PrairieMetadata.Sequence` | `firstSequence` The first actual `<Sequence>` element.
    `private PrairieMetadata.ValueTable` | `scanValues` Table of key/value pairs at the top level.
    `private java.util.HashMap<java.lang.Integer,PrairieMetadata.Sequence>` | `sequences` `<Sequence>` elements, keyed on each sequence's `cycle`.
    `private java.lang.Double` | `waitTime` The wait time of the acquisition.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PrairieMetadata(org.w3c.dom.Document xml, org.w3c.dom.Document cfg, org.w3c.dom.Document env)` Creates a new Prairie metadata by parsing the given XML, CFG and/or ENV documents.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `private java.lang.String` | `attr(org.w3c.dom.Element el, java.lang.String name)` Gets the attribute value with the given name, or null if not defined.
    `private boolean` | `b(java.lang.String value)` Converts the given string to a `boolean`.
    `private void` | `checkElement(org.w3c.dom.Element el, java.lang.String name)` Checks that the given element has the specified name.
    `private java.lang.Double` | `d(java.lang.String value)` Converts the given string to a `Double`, or `null` if incompatible.
    `private org.w3c.dom.Element` | `el(org.w3c.dom.NodeList nodes, int index)` Gets the `index`th element from the given list of nodes.
    `int[]` | `getActiveChannels()` Gets the list of active channel indices, in sorted order.
    `java.lang.Integer` | `getBitDepth()` Gets the `bitDepth` recorded in the configuration.
    `PrairieMetadata.ValueTable` | `getConfig()` Gets the map of configuration key/value pairs.
    `PrairieMetadata.Value` | `getConfig(java.lang.String key)` Gets the `value` of the given configuration `key`.
    `int` | `getCycleCount()` Gets the number of recorded cycles.
    `int` | `getCycleMax()` Gets the maximum cycle value.
    `int` | `getCycleMin()` Gets the minimum cycle value.
    `java.lang.String` | `getDate()` Gets the date of the acquisition.
    `PrairieMetadata.PFile` | `getFile(int cycle, int index, int channel)` Gets the `Frame` at the given (`cycle`, `index`, `channel`).
    `private org.w3c.dom.Element` | `getFirstChild(org.w3c.dom.Element el, java.lang.String name)` Gets the first child element with the given name.
    `PrairieMetadata.Sequence` | `getFirstSequence()` Gets the first `Sequence`.
    `PrairieMetadata.Frame` | `getFrame(int cycle, int index)` Gets the `Frame` at the given (`cycle` and `index`).
    `java.lang.Double` | `getLaserPower()` Gets the first `laserPower` recorded in the configuration.
    `PrairieMetadata.Sequence` | `getSequence(int cycle)` Gets the `Sequence` at the given `cycle`.
    `java.util.ArrayList<PrairieMetadata.Sequence>` | `getSequences()` Gets all `Sequences`, ordered by `cycle`.
    `PrairieMetadata.Value` | `getValue(java.lang.String key)` Gets the `value` of the given `key`, at the top-level `<PVScan>` element.
    `PrairieMetadata.ValueTable` | `getValues()` Gets the table of `PVScan` key/value pairs.
    `java.lang.Double` | `getWaitTime()` Gets the `waitTime` recorded in the configuration.
    `private java.lang.Integer` | `i(java.lang.String value)` Converts the given string to an `Integer`, or null if incompatible.
    `boolean` | `isInvertX()` Gets whether the stage position X coordinates are inverted (i.e., left-to-right).
    `boolean` | `isInvertY()` Gets whether the stage position Y coordinates are inverted (i.e., bottom-to-top).
    `private void` | `parseCFG(org.w3c.dom.Document doc)` Parses metadata from Prairie CFG file.
    `private void` | `parseChannels()` Parses details of the activated channels into the `activeChannels` data structure from the "channel" entry of the configuration.
    `private void` | `parseENV(org.w3c.dom.Document doc)` Parses metadata from Prairie ENV file.
    `private void` | `parseKeys(org.w3c.dom.Element el, PrairieMetadata.ValueTable table)` Parses `<Key>` elements beneath the given element, into the specified table.
    `private void` | `parsePVStateShard(org.w3c.dom.Element el, PrairieMetadata.ValueTable table)` Parses the `<PVStateShard>` element beneath the given element, into the specified table.
    `private void` | `parseXML(org.w3c.dom.Document doc)` Parses metadata from Prairie XML file.
    `private java.lang.String` | `token(java.lang.String s, java.lang.String regex, int i)` Gets the `i`th token of the given string, split according to the specific regular expression.
    `private java.lang.String` | `value(PrairieMetadata.Value value)` Returns `value.value()`, or null if `value` is null.
    `private java.lang.String` | `value(PrairieMetadata.Value value, int index)` Returns `value.get(index).value()`, or null if `value` or `value.get(index)` is null.
    `private java.lang.String` | `value(PrairieMetadata.Value value, java.lang.String key)` Returns `value.get(key).value()`, or null if `value` or `value.get(key)` is null.
    `private <K extends java.lang.Comparable<? super K>,V> java.util.ArrayList<V>` | `valuesByKey(java.util.Map<K,V> map)` Gets the values of the given map, sorted by key.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### sequences

          private final java.util.HashMap<java.lang.Integer,PrairieMetadata.Sequence> sequences

      `<Sequence>` elements, keyed on each sequence's `cycle`.

    - #### scanValues

          private final PrairieMetadata.ValueTable scanValues

      Table of key/value pairs at the top level.

    - #### firstSequence

          private PrairieMetadata.Sequence firstSequence

      The first actual `<Sequence>` element.

    - #### cycleMin

          private int cycleMin

      Minimum cycle value.

    - #### cycleMax

          private int cycleMax

      Maximum cycle value.

    - #### date

          private java.lang.String date

      The date of the acquisition.

    - #### waitTime

          private java.lang.Double waitTime

      The wait time of the acquisition.

    - #### activeChannels

          private final java.util.HashSet<java.lang.Integer> activeChannels

      Set of active channel indices.

    - #### config

          private final PrairieMetadata.ValueTable config

      Key/value pairs from CFG and/or ENV files.

  - ### Constructor Detail

    - #### PrairieMetadata

          public PrairieMetadata(org.w3c.dom.Document xml,
                                 org.w3c.dom.Document cfg,
                                 org.w3c.dom.Document env)

      Creates a new Prairie metadata by parsing the given XML, CFG and/or ENV documents.
      Parameters:
        `xml` - The XML document to parse, or null if none available.
        `cfg` - The CFG document to parse, or null if none available.
        `env` - The ENV document to parse, or null if none available.

  - ### Method Detail

    - #### getWaitTime

          public java.lang.Double getWaitTime()

      Gets the `waitTime` recorded in the configuration.

    - #### getActiveChannels

          public int[] getActiveChannels()

      Gets the list of active channel indices, in sorted order.

      These indices correspond to the configuration's `channel` keys flagged as `True`.

    - #### isInvertX

          public boolean isInvertX()

      Gets whether the stage position X coordinates are inverted (i.e., left-to-right).

    - #### isInvertY

          public boolean isInvertY()

      Gets whether the stage position Y coordinates are inverted (i.e., bottom-to-top).

    - #### getBitDepth

          public java.lang.Integer getBitDepth()

      Gets the `bitDepth` recorded in the configuration.

    - #### getLaserPower

          public java.lang.Double getLaserPower()

      Gets the first `laserPower` recorded in the configuration.

    - #### getConfig

          public PrairieMetadata.Value getConfig(java.lang.String key)

      Gets the `value` of the given configuration `key`.

    - #### getConfig

          public PrairieMetadata.ValueTable getConfig()

      Gets the map of configuration key/value pairs.

    - #### getDate

          public java.lang.String getDate()

      Gets the date of the acquisition.

    - #### getCycleMin

          public int getCycleMin()

      Gets the minimum cycle value. Matches the smallest `cycle` attribute found, and hence will not necessarily equal `1` (though in practice it usually does).

    - #### getCycleMax

          public int getCycleMax()

      Gets the maximum cycle value. Matches the largest `cycle` attribute found, and hence will not necessarily equal `sequences#size()` (though in practice it usually does).

    - #### getCycleCount

          public int getCycleCount()

      Gets the number of recorded cycles. This value is equal to `getCycleMax()` - `getCycleMin()` + 1.

    - #### getFirstSequence

          public PrairieMetadata.Sequence getFirstSequence()

      Gets the first `Sequence`.

    - #### getSequence

          public PrairieMetadata.Sequence getSequence(int cycle)

      Gets the `Sequence` at the given `cycle`.

    - #### getSequences

          public java.util.ArrayList<PrairieMetadata.Sequence> getSequences()

      Gets all `Sequences`, ordered by `cycle`.

    - #### getFrame

          public PrairieMetadata.Frame getFrame(int cycle,
                                                int index)

      Gets the `Frame` at the given (`cycle` and `index`).

    - #### getFile

          public PrairieMetadata.PFile getFile(int cycle,
                                               int index,
                                               int channel)

      Gets the `Frame` at the given (`cycle`, `index`, `channel`).

    - #### getValue

          public PrairieMetadata.Value getValue(java.lang.String key)

      Gets the `value` of the given `key`, at the top-level `<PVScan>` element.

    - #### getValues

          public PrairieMetadata.ValueTable getValues()

      Gets the table of `PVScan` key/value pairs.

    - #### parseXML

          private void parseXML(org.w3c.dom.Document doc)

      Parses metadata from Prairie XML file.

    - #### parseCFG

          private void parseCFG(org.w3c.dom.Document doc)

      Parses metadata from Prairie CFG file. This file is only present for Prairie datasets recorded prior to version 5.2.

    - #### parseENV

          private void parseENV(org.w3c.dom.Document doc)

      Parses metadata from Prairie ENV file. This file is only present for Prairie datasets recorded with version 5.2 or later.

    - #### parseKeys

          private void parseKeys(org.w3c.dom.Element el,
                                 PrairieMetadata.ValueTable table)

      Parses `<Key>` elements beneath the given element, into the specified table. These `<Key>` elements are only present in data from PrairieView versions prior to 5.2.

    - #### parsePVStateShard

          private void parsePVStateShard(org.w3c.dom.Element el,
                                         PrairieMetadata.ValueTable table)

      Parses the `<PVStateShard>` element beneath the given element, into the specified table. These `<PVStateShard>` elements are only present in data from PrairieView versions 5.2 and later.

    - #### parseChannels

          private void parseChannels()

      Parses details of the activated channels into the `activeChannels` data structure from the "channel" entry of the configuration.

    - #### checkElement

          private void checkElement(org.w3c.dom.Element el,
                                    java.lang.String name)

      Checks that the given element has the specified name.
      Throws:
        `java.lang.IllegalArgumentException` - if the name does not match.

    - #### getFirstChild

          private org.w3c.dom.Element getFirstChild(org.w3c.dom.Element el,
                                                    java.lang.String name)

      Gets the first child element with the given name.

    - #### el

          private org.w3c.dom.Element el(org.w3c.dom.NodeList nodes,
                                         int index)

      Gets the `index`th element from the given list of nodes.

    - #### attr

          private java.lang.String attr(org.w3c.dom.Element el,
                                        java.lang.String name)

      Gets the attribute value with the given name, or null if not defined.

    - #### value

          private java.lang.String value(PrairieMetadata.Value value)

      Returns `value.value()`, or null if `value` is null.

    - #### value

          private java.lang.String value(PrairieMetadata.Value value,
                                         java.lang.String key)

      Returns `value.get(key).value()`, or null if `value` or `value.get(key)` is null.

    - #### value

          private java.lang.String value(PrairieMetadata.Value value,
                                         int index)

      Returns `value.get(index).value()`, or null if `value` or `value.get(index)` is null.

    - #### b

          private boolean b(java.lang.String value)

      Converts the given string to a `boolean`.

    - #### d

          private java.lang.Double d(java.lang.String value)

      Converts the given string to a `Double`, or `null` if incompatible.

    - #### i

          private java.lang.Integer i(java.lang.String value)

      Converts the given string to an `Integer`, or null if incompatible.

    - #### token

          private java.lang.String token(java.lang.String s,
                                         java.lang.String regex,
                                         int i)

      Gets the `i`th token of the given string, split according to the specific regular expression.

    - #### valuesByKey

          private <K extends java.lang.Comparable<? super K>,V> java.util.ArrayList<V> valuesByKey(java.util.Map<K,V> map)

      Gets the values of the given map, sorted by key.

Copyright © 2026 Open Microscopy Environment