Package loci.formats

Class FilePattern

java.lang.Object
loci.formats.FilePattern
public class FilePattern extends Object
Represents a collection of files meant to be part of the same data series.

A file pattern can be constructed from a pattern string, where variable parts are represented by blocks delimited by angle brackets. For instance, the pattern img_<R,G,B>.ext expands to img_R.ext, img_G.ext and img_B.ext.

In addition to comma-separated series as the one shown above, pattern blocks can contain a sequence expression in the START-STOP:STEP format. For instance, the pattern <0-36:3>m.tiff expands to 0m.tiff, 3m.tiff, 6m.tiff ... 36m.tiff. If the step increment is one, it can be omitted: TAABA<1-3>.PIC expands to TAABA1.PIC, TAABA2.PIC, TAABA3.PIC. The start number can have leading zeroes to denote zero-padded numbers: img_<08-10>.ext expands to img_08.ext, img_09.ext, img_10.ext. Sequence expressions also support alphabetic ranges: img_<C-E>.ext expands to img_C.ext, img_D.ext, img_E.ext.

A multi-block pattern is expanded by substituting the blocks with the tuples from the cartesian product of all block expansions. For instance, z<1-2><R,G,B>.tiff expands to z1R.tiff, z1G.tiff, z1B.tiff, z2R.tiff, z2G.tiff, z2B.tiff.

If a pattern has zero blocks, it will be treated as a regular expression to be matched against the names of existing files. If there are no matches, the pattern expands to itself. For instance, /tmp/z.*.tif expands to /tmp/z1.tif if that file exists (and it's the only matching file), otherwise it expands to itself. If the pattern contains no special regex syntax, it also expands to itself (a single file is a special case of file pattern).

A FilePattern can also be created from a Location or from a basename and directory. In these cases, the pattern string is inferred from the names of other files in the same directory.

Author:
Curtis Rueden ctrueden at wisc.edu

  • Field Details

    • pattern

      private String pattern
      The file pattern string.

    • valid

      private boolean valid
      The validity of the file pattern.

    • msg

      private String msg
      Error message generated during file pattern construction.

    • startIndex

      private int[] startIndex
      Indices into the pattern indicating the start of a numerical block.

    • endIndex

      private int[] endIndex
      Indices into the pattern indicating the end of a numerical block.

    • blocks

      private FilePatternBlock[] blocks
      List of pattern blocks for this file pattern.

    • files

      private String[] files
      File listing for this file pattern.

    • isRegex

      private boolean isRegex
      Whether or not this FilePattern represents a regular expression.

  • Constructor Details

    • FilePattern

      public FilePattern(loci.common.Location file)
      Creates a pattern object using the given file as a template.
      Parameters:
      file - the file as a Location instance.

    • FilePattern

      public FilePattern(String name, String dir)
      Creates a pattern object using the given filename and directory path as a template.
      Parameters:
      name - file basename.
      dir - directory path.

    • FilePattern

      public FilePattern(String pattern)
      Creates a pattern object for files with the given pattern string.
      Parameters:
      pattern - the pattern string.

  • Method Details

    • isRegex

      public boolean isRegex()
      Returns whether or not this pattern is a regular expression.
      Returns:
      true if this pattern is a regex, false otherwise.

    • getPattern

      public String getPattern()
      Gets the file pattern string.
      Returns:
      the pattern string.

    • isValid

      public boolean isValid()
      Returns whether or not the file pattern is valid.
      Returns:
      true if the pattern is valid, false otherwise.

    • getErrorMessage

      public String getErrorMessage()
      Gets the file pattern error message, if any.
      Returns:
      the error message generated while parsing the pattern string, or null if there was no error.

    • getFiles

      public String[] getFiles()
      Gets a listing of all files matching this file pattern.
      Returns:
      an array containing all file names that match this pattern.

    • getElements

      public String[][] getElements()
      Gets individual elements for each pattern block.
      Returns:
      an array containing an array of individual elements for each pattern block.

    • getCount

      public int[] getCount()
      Gets the number of elements for each pattern block.
      Returns:
      an array containing the number of individual elements for each pattern block.

    • getBlock

      public String getBlock(int i)
      Gets the specified file pattern block (e.g., <0-9>).
      Parameters:
      i - block index
      Returns:
      the ith pattern block.

    • getBlocks

      public String[] getBlocks()
      Gets all file pattern blocks.
      Returns:
      an array containing all pattern blocks.

    • getPrefix

      public String getPrefix()
      Gets the pattern's substring that comes before any block sections. For instance, the prefix of "img_z<0-2>t<1-3>_gs.ext" is "img_z".
      Returns:
      the prefix string as described above.

    • getSuffix

      public String getSuffix()
      Gets the pattern's substring that comes after all block sections. For instance, the suffix of "img_z<0-2>t<1-3>_gs.ext" is "_gs.ext".
      Returns:
      the suffix string as described above.

    • getPrefix

      public String getPrefix(int i)
      Gets the pattern's substring between block i-1 (or the beginning of the pattern, if i is 0) and block i. For instance, the second (i = 1) prefix of "img_z<0-2>t<1-3>_gs.ext" is "t".
      Parameters:
      i - block index.
      Returns:
      the ith prefix as defined above.

    • getPrefixes

      public String[] getPrefixes()
      Gets all block prefixes. For instance, the prefixes of "img_z<0-2>t<1-3>_gs.ext" are "img_z" and "t".
      Returns:
      an array containing all block prefixes.

    • findPattern

      public static String findPattern(String path)
      Identifies the group pattern from a given file within that group.
      Parameters:
      path - The file path to use as a template for the match.
      Returns:
      the identified pattern.

    • findPattern

      public static String findPattern(loci.common.Location file)
      Identifies the group pattern from a given file within that group.
      Parameters:
      file - The Location to use as a template for the match.
      Returns:
      the identified pattern.

    • findPattern

      public static String findPattern(File file)
      Identifies the group pattern from a given file within that group.
      Parameters:
      file - The file to use as a template for the match.
      Returns:
      the identified pattern.

    • findPattern

      public static String findPattern(String name, String dir)
      Identifies the group pattern from a given filename and directory.
      Parameters:
      name - The file basename to use as a template for the match.
      dir - The directory in which to search for matching files.
      Returns:
      the identified pattern.

    • findPattern

      public static String findPattern(String name, String dir, String[] nameList)
      Identifies the group pattern from a given filename, directory and list of candidate filenames.
      Parameters:
      name - The file basename to use as a template for the match.
      dir - The directory prefix to use for matching files.
      nameList - The names through which to search for matching files.
      Returns:
      the identified pattern.

    • findPattern

      public static String findPattern(String name, String dir, String[] nameList, int[] excludeAxes)
      Identifies the group pattern from a given filename, directory and list of candidate filenames.
      Parameters:
      name - The file basename to use as a template for the match.
      dir - The directory prefix to use for matching files.
      nameList - The names through which to search for matching files.
      excludeAxes - The list of axis types which should be excluded from the pattern (see AxisGuesser).
      Returns:
      the identified pattern.

    • findPattern

      public static String findPattern(String[] names)
      Generate a pattern from a list of file names. The pattern generated will be a regular expression. Currently assumes that all file names are in the same directory.
      Parameters:
      names - the list of filenames.
      Returns:
      the generated pattern.

    • findSeriesPatterns

      public static String[] findSeriesPatterns(String base)
      Works like findSeriesPatterns(String, String, String[]), but dir and nameList are inferred from the given file's absolute path.
      Parameters:
      base - The file basename to use as a template for the match.
      Returns:
      an array containing all identified patterns.

    • findSeriesPatterns

      public static String[] findSeriesPatterns(String base, String dir, String[] nameList)
      Similar to findPattern(String, String, String[]), but this does not merge series indices into a pattern block. Instead, it returns a separate pattern for each series index. For instance, if the file names are: "foo_s1_z1.ext", "foo_s1_z2.ext", "foo_s2_z1.ext", "foo_s2_z2.ext" Then findPattern will find a single "foo_s<1-2>_z<1-2>.ext" pattern, whereas this method will find "foo_s1_z<1-2>.ext" and "foo_s2_z<1-2>.ext".
      Parameters:
      base - The file basename to use as a template for the match.
      dir - The directory prefix to use for matching files.
      nameList - The names through which to search for matching files.
      Returns:
      an array containing all identified patterns.

    • findPattern

      private static String findPattern(String name, String[] nameList, int ndx, int end, String p)

    • getBounds

      private static String getBounds(BigInteger[] numbers, boolean fixed)
      Gets a string containing start, end and step values for a sorted list of numbers.
      Parameters:
      numbers - a sorted list of numbers
      fixed - whether the numbers to a fixed width block
      Returns:
      block bounds as a <START-STOP:STEP> expression

    • matchFiles

      private static String[] matchFiles(String[] inFiles, NumberFilter filter)

    • buildFiles

      private void buildFiles(String prefix, int ndx, List<String> fileList)

    • getAllFiles

      private String[] getAllFiles(String dir)

    • getFirst

      public BigInteger[] getFirst()
      Gets the START element for all blocks.
      Returns:
      an array containing all START elements.

    • getLast

      public BigInteger[] getLast()
      Gets the STOP element for all blocks.
      Returns:
      an array containing all STOP elements.

    • getStep

      public BigInteger[] getStep()
      Gets the STEP element for all blocks.
      Returns:
      an array containing all STEP elements.