A nifty way to parse your file sequences.
The seqparse module may be used to …
- Scan specified paths for file sequences and “singletons,”
- Construct frame and file sequence from supplied values, and
- Query disk for overall footprint of tracked files.
The module also comes supplied with a simple tool named seqls that allows the user to scan multiple locations for file sequences and singletons from the command line.
If you’re curious about the regular expressions used to determine what is and isn’t a valid file sequence, take a look at the seqparse.regex module.
Frame sequences are broken down into comma-separated chunks of the format first frame - last frame x step where the following rules apply:
- Frame numbers can be zero-padded,
- Frame step (increment) is always a positive integer,
- The number of digits in a frame may exceed the padding of a sequence, eg 001,010,100,1000,
- Frame chunks with a specified step will always consist of three or more frames.
Examples of proper frame sequences:
- Non-padded sequence, frames == (1, 3, 5, 7): 1-7x2
- Four-padded sequence, frames == (1, 3, 5, 7): 0001-0007x2
- Three-padded sequence, frames == (11, 13): 011,013
- Two-padded sequence (1, 3, 5, 7, 11, 13, 102): 01-07x2,11,13,102
Members of a file sequence can be one of two formats:
Examples of valid file sequences:
seqls is the command line interface for the seqparse module.
usage: seqls [-h] [-a] [-H] [-l] [--maxdepth MAX_LEVELS] [--mindepth MIN_LEVELS] [-m] [-S] [search_path [search_path ...]] Command line tool for listing file sequences. Upon installation of the package this script will be accessable via ``seqls`` command on the command line of your choice. positional arguments: search_path Paths that you'd like to search for file sequences. optional arguments: -h, --help show this help message and exit -a, --all Do not ignore entries starting with '.'. -H, --human-readable with -l/--long, print sizes in human readable format (e.g., 1K 234M 2G). -l, --long Use a long listing format. --maxdepth MAX_LEVELS Descend at most levels (a non-negative integer) MAX_LEVELS of directories below the starting-points. '--maxdepth 0' means scan the starting-points themselves. --mindepth MIN_LEVELS Do not scan at levels less than MIN_LEVELS (a non- negative integer). '--mindepth 1' means scan all levels except the starting-points. -m, --missing Whether to invert output file sequences to only report the missing frames. -S, --seqs-only Whether to filter out all non-sequence files. -v, --version Print the version and exit.
Most of the functionality is self-explanatory, but the -m/--missing option is probably the most useful to users generating large sequences of frames on multiple servers.
Say you’re creating imagery for the latest superhero movie – and your render job crashed some time in the early morning.
You’re expecting to see something like this …
… but not everything rendered.
$ cd /renders/superhero_cape_v0001 $ seqls superhero_cape_v0001.0001-0500,0600-0800,0990-1000x5.exr
You can easily figure out the missing frames, though, with the --missing option:
$ seqls --missing superhero_cape_v0001.0501-0599,0801,0991-0994,0996-0999.exr
Using the module is fairly simple:
- Instantiate a parser (Seqparse instance).
- Add files to the parser either
- via the add_file method, or
- by scanning a list of locations on disk via the scan_path method.
- Create an iterator for all file sequences (FileSequence instances) and singletons (File instances).
Example (taken from the Seqparse docstring):
With the following file structure ... test_dir/ TEST_DIR.0001.tif TEST_DIR.0002.tif TEST_DIR.0003.tif TEST_DIR.0004.tif TEST_DIR.0010.tif SINGLETON.jpg >>> from seqparse.seqparse import Seqparse >>> parser = Seqparse() >>> parser.scan_path("test_dir") >>> for item in parser.output(): ... print(str(item)) ... test_dir/TEST_DIR.0001-0004,0010.tif test_dir/SINGLETON.jpg >>> for item in parser.output(seqs_only=True): ... print(str(item)) ... test_dir/TEST_DIR.0001-0004,0010.tif >>> for item in parser.output(missing=True): ... print(str(item)) ... test_dir/TEST_DIR.0005-0009.tif
FrameSequence instances are pretty useful on their own.
>>> from seqparse import get_sequence >>> seq = get_sequence([1, 2, 3, 4, 8]) >>> print(repr(seq)) FrameSequence(pad=4, frames=set([1, 2, 3, 4, 8])) >>> print(seq) 0001-0005,0008 >>> for frame in seq: ... print(frame) ... 0001 0002 0003 0004 0010 >>> for frame in seq.invert(): ... print(frame) ... 0005 0006 0007
As are FileSequence instances (which behave similarly; check class documentation for details).
I’m moderately happy with this code – but there’s always room for improvement (and new/exciting features).
Lemme know if you have any requests/complaints/suggestions!