Documentation ¶
Overview ¶
Package fileseq is a library for parsing file sequence strings commonly used in VFX and animation applications.
Frame Range Shorthand ¶
Support for:
Standard: 1-10 Comma Delimited: 1-10,10-20 Chunked: 1-100x5 Filled: 1-100y5 Staggered: 1-100:3 (1-100x3, 1-100x2, 1-100) Negative frame numbers: -10-100 Padding: #=4 padded, @=single pad
Index ¶
- Constants
- func FramesToFrameRange(frames []int, sorted bool, zfill int) string
- func IsFrameRange(frange string) bool
- func PadFrameRange(frange string, pad int) string
- func PaddingChars(pad int) string
- type FileOption
- type FileSequence
- func FindSequenceOnDisk(pattern string, opts ...FileOption) (*FileSequence, error)
- func FindSequenceOnDiskPad(pattern string, padStyle PadStyle, opts ...FileOption) (*FileSequence, error)
- func NewFileSequence(sequence string) (*FileSequence, error)
- func NewFileSequencePad(sequence string, style PadStyle) (*FileSequence, error)
- func (s *FileSequence) Basename() string
- func (s *FileSequence) Copy() *FileSequence
- func (s *FileSequence) Dirname() string
- func (s *FileSequence) End() int
- func (s *FileSequence) Ext() string
- func (s *FileSequence) Format(tpl string) (string, error)
- func (s *FileSequence) Frame(frame interface{}) (string, error)
- func (s *FileSequence) FrameRange() string
- func (s *FileSequence) FrameRangePadded() string
- func (s *FileSequence) FrameSet() *FrameSet
- func (s *FileSequence) Index(idx int) string
- func (s *FileSequence) InvertedFrameRange() string
- func (s *FileSequence) InvertedFrameRangePadded() string
- func (s *FileSequence) Len() int
- func (s *FileSequence) Padding() string
- func (s *FileSequence) PaddingStyle() PadStyle
- func (s *FileSequence) SetBasename(base string)
- func (s *FileSequence) SetDirname(dir string)
- func (s *FileSequence) SetExt(ext string)
- func (s *FileSequence) SetFrameRange(frameRange string) error
- func (s *FileSequence) SetFrameSet(frameSet *FrameSet)
- func (s *FileSequence) SetPadding(padChars string)
- func (s *FileSequence) SetPaddingStyle(style PadStyle)
- func (s *FileSequence) Split() FileSequences
- func (s *FileSequence) Start() int
- func (s *FileSequence) String() string
- func (s *FileSequence) ZFill() int
- type FileSequences
- type FrameSet
- func (s *FrameSet) End() int
- func (s *FrameSet) Frame(index int) (int, error)
- func (s *FrameSet) FrameRange() string
- func (s *FrameSet) FrameRangePadded(pad int) string
- func (s *FrameSet) Frames() []int
- func (s *FrameSet) HasFrame(frame int) bool
- func (s *FrameSet) Index(frame int) int
- func (s *FrameSet) Invert() *FrameSet
- func (s *FrameSet) InvertedFrameRange(pad int) string
- func (s *FrameSet) Len() int
- func (s *FrameSet) Normalize() *FrameSet
- func (s *FrameSet) Start() int
- func (s *FrameSet) String() string
- type PadStyle
Constants ¶
const Version = "2.6.0"
Variables ¶
This section is empty.
Functions ¶
func FramesToFrameRange ¶
FramesToFrameRange takes a slice of frame numbers and compresses them into a frame range string.
If sorted == true, pre-sort the frames instead of respecting their current order in the range.
If zfill > 1, then pad out each number with "0" to the given total width.
func IsFrameRange ¶
IsFrameRange returns true if the given string is a valid frame range format. Any padding characters, such as '#' and '@' are ignored.
func PadFrameRange ¶
PadFrameRange takes a frame range string and returns a new range with each number padded out with zeros to a given width
func PaddingChars ¶
PaddingChars returns the proper padding characters, given an amount of padding. Uses PadStyleDefault.
Types ¶
type FileOption ¶
type FileOption int
FileOption indicate how file listings should be performed and returned
const ( // HiddenFiles includes hidden files in file listings HiddenFiles FileOption = iota // SingleFiles includes paths that aren't detected as sequences, and are // just single files SingleFiles // FileOptPadStyleHash1 sets the PadStyle to PadStyleHash1 FileOptPadStyleHash1 // FileOptPadStyleHash4 sets the PadStyle to PadStyleHash4 FileOptPadStyleHash4 // StrictPadding instructs FindSequenceOnDisk to consider the padding // length of the search pattern, and to ignore files with a different padding StrictPadding )
type FileSequence ¶
type FileSequence struct {
// contains filtered or unexported fields
}
A FileSequence represents a path to a sequence of files, and expresses a valid frames range (one that can be parsed by FrameSet. It also includes one or more padding characters to dictate how much padding the actual file numbers have.
Valid padding characters:
@ - 1 pad width (@@@@ is equal to 4 padding) # - 4 pad width (## is equal to 8 padding)
Example paths and padding:
/path/to/single_image.0100.jpg /path/to/image_foo.1-10x2#.jpg (i.e. 0001) /path/to/image_foo.1-10x2@.jpg (i.e. 1) /path/to/image_foo.1-10x2@@@.jpg (i.e. 001)
func FindSequenceOnDisk ¶
func FindSequenceOnDisk(pattern string, opts ...FileOption) (*FileSequence, error)
FindSequenceOnDisk takes a string that is a compatible/parsible FileSequence pattern, and finds a sequence on disk which matches the Basename and Extension.
By default the patterns frame value and padding characters are ignored and replaced by a wildcard '*' glob. If you want to match on a specific frame padding length, pass the option StrictPadding
If no match is found, a nil FileSequence is returned. If an error occurs while reading the filesystem, a non-nil error is returned.
Example:
// Find matches with any frame value FindSequenceOnDisk("/path/to/seq.#.ext") // Find matches specifically having 4-padded frames FindSequenceOnDisk("/path/to/seq.#.ext", StrictPadding)
func FindSequenceOnDiskPad ¶
func FindSequenceOnDiskPad(pattern string, padStyle PadStyle, opts ...FileOption) (*FileSequence, error)
FindSequenceOnDiskPad takes a string that is a compatible/parsible FileSequence pattern, and finds a sequence on disk which matches the Basename and Extension. The returned seq will use the given PadStyle.
By default the patterns frame value and padding characters are ignored and replaced by a wildcard '*' glob. If you want to match on a specific frame padding length, pass the option StrictPadding
If no match is found, a nil FileSequence is returned. If an error occurs while reading the filesystem, a non-nil error is returned.
func NewFileSequence ¶
func NewFileSequence(sequence string) (*FileSequence, error)
NewFileSequence returns a FileSequence from a string sequence path. The path should be a valid sequence, expressing a frame range, or a single file path. If error is non-nil, then the given sequence string could not be successfully parsed.
PadStyleDefault is used as the padding character formatter ¶
Example paths:
/path/to/image_foo.1-10x2#.jpg /path/to/single_image.0100.jpg
func NewFileSequencePad ¶
func NewFileSequencePad(sequence string, style PadStyle) (*FileSequence, error)
NewFileSequencePad returns a FileSequence from a string sequence path. The path should be a valid sequence, expressing a frame range, or a single file path. If error is non-nil, then the given sequence string could not be successfully parsed.
The sequence uses the style of padding given, in order to convert between padding characters and their numeric width.
Example path w/ PadStyleHash1:
/path/to/image_foo.1-10x2#.jpg => /path/to/image_foo.1.jpg ... /path/to/image_foo.1-10x2@.jpg => /path/to/image_foo.1.jpg ... /path/to/image_foo.1-10x2##.jpg => /path/to/image_foo.01.jpg ...
Example path w/ PadStyleHash4:
/path/to/image_foo.1-10x2#.jpg => /path/to/image_foo.0001.jpg ... /path/to/image_foo.1-10x2@.jpg => /path/to/image_foo.1.jpg ... /path/to/image_foo.1-10x2##.jpg => /path/to/image_foo.00000001.jpg ...
func (*FileSequence) Basename ¶
func (s *FileSequence) Basename() string
Basename returns the parsed basename component of the sequence string. This is the file part, just before the frame range component.
func (*FileSequence) Copy ¶
func (s *FileSequence) Copy() *FileSequence
Copy returns a copy of the FileSequence
func (*FileSequence) Dirname ¶
func (s *FileSequence) Dirname() string
Dirname returns the parsed directory component of the sequence string
func (*FileSequence) End ¶
func (s *FileSequence) End() int
End returns the ending frame of the sequence. If a frame range/number could not be parsed, then this will always return 0
func (*FileSequence) Ext ¶
func (s *FileSequence) Ext() string
Ext returns the file extension component from the sequence, including the leading period character.
func (*FileSequence) Format ¶
func (s *FileSequence) Format(tpl string) (string, error)
Format returns the file sequence as a formatted string according to the given template.
Utilizes Go text/template format syntax. Available functions include:
dir - the directory name. base - the basename of the sequence (leading up to the frame range). ext - the file extension of the sequence including leading period. startf - the start frame. endf - the end frame. len - the length of the frame range. pad - the detected padding characters (i.e. # , @@@ , ...). frange - the frame range. inverted - the inverted frame range. (returns empty string if none) zfill - the int width of the frame padding
Example:
{{dir}}{{base}}{{frange}}{{pad}}{{ext}}
func (*FileSequence) Frame ¶
func (s *FileSequence) Frame(frame interface{}) (string, error)
Frame returns a path to the given frame in the sequence. Integer or string digits are treated as a frame number and padding is applied, all other values are passed though. Accepts ints, strings, []byte, and Stringer types
Example:
seq.Frame(1) >> /foo/bar.0001.exr seq.Frame("#") >> /foo/bar.#.exr
func (*FileSequence) FrameRange ¶
func (s *FileSequence) FrameRange() string
FrameRange returns the string frame range component, parsed from the sequence. If no frame range was parsed, then this method will return an empty string.
func (*FileSequence) FrameRangePadded ¶
func (s *FileSequence) FrameRangePadded() string
FrameRangePadded returns the string frame range component, parsed from the sequence, and padded out by the pad characters. If no frame range was parsed, then this method will return an empty string.
func (*FileSequence) FrameSet ¶
func (s *FileSequence) FrameSet() *FrameSet
FrameSet returns a FrameSet instance that was created when the sequence was parsed. If no frame range was parsed from the sequence, then this method will return nil
func (*FileSequence) Index ¶
func (s *FileSequence) Index(idx int) string
Index returns the path to the file at the given index in the sequence. If a frame range was not parsed from the sequence, this will always returns the original path. If the index is not valid, this will return an empty string.
func (*FileSequence) InvertedFrameRange ¶
func (s *FileSequence) InvertedFrameRange() string
InvertedFrameRange returns a new frame range that represents all frames *not* within the current frame range. That is, it will create a range that "fills in" the current one.
func (*FileSequence) InvertedFrameRangePadded ¶
func (s *FileSequence) InvertedFrameRangePadded() string
InvertedFrameRangePadded returns a new frame range that represents all frames *not* within the current frame range. That is, it will create a range that "fills in" the current one. Frames are padded out to the zfill width.
func (*FileSequence) Len ¶
func (s *FileSequence) Len() int
Len returns the number of frames in the FrameSet. If a frame range was not parsed, this will always return 1
func (*FileSequence) Padding ¶
func (s *FileSequence) Padding() string
Padding returns the parsed padding characters component of the sequence string. May return an empty string if the file sequence was really a single file. i.e. # or @ or @@@
func (*FileSequence) PaddingStyle ¶
func (s *FileSequence) PaddingStyle() PadStyle
PaddingStyle returns the style of padding being used to convert between characters and their numeric width, i.e. # == 4
func (*FileSequence) SetBasename ¶
func (s *FileSequence) SetBasename(base string)
Set a new basename for the sequence
func (*FileSequence) SetDirname ¶
func (s *FileSequence) SetDirname(dir string)
Set a new dirname for the sequence
func (*FileSequence) SetExt ¶
func (s *FileSequence) SetExt(ext string)
Set a new ext for the sequence
func (*FileSequence) SetFrameRange ¶
func (s *FileSequence) SetFrameRange(frameRange string) error
Set a new FrameSet, by way of providing a string frame range. If the frame range cannot be parsed, an error will be returned.
func (*FileSequence) SetFrameSet ¶
func (s *FileSequence) SetFrameSet(frameSet *FrameSet)
Set a new FrameSet for the sequence
func (*FileSequence) SetPadding ¶
func (s *FileSequence) SetPadding(padChars string)
Set a new padding characters for the sequence
func (*FileSequence) SetPaddingStyle ¶
func (s *FileSequence) SetPaddingStyle(style PadStyle)
Set a new padding style for mapping between characters and their numeric width
func (*FileSequence) Split ¶
func (s *FileSequence) Split() FileSequences
Split a non-contiguous (i.e. comma-separated) sequence into a list of sequences that each use consistent stepping
func (*FileSequence) Start ¶
func (s *FileSequence) Start() int
Start returns the starting frame of the sequence. If a frame range/number could not be parsed, then this will always return 0
func (*FileSequence) String ¶
func (s *FileSequence) String() string
String returns the formatted sequence
func (*FileSequence) ZFill ¶
func (s *FileSequence) ZFill() int
ZFill returns the number of "0" fill characters used to pad the frame numbers to match the actual file paths
type FileSequences ¶
type FileSequences []*FileSequence
FileSequences is a slice of FileSequence pointers, which can be sorted
func FindSequencesOnDisk ¶
func FindSequencesOnDisk(path string, opts ...FileOption) (FileSequences, error)
FindSequencesOnDisk searches a given directory path and sorts all valid sequence-compatible files into a list of FileSequences
By default, only non-hidden sequences of files will be returned. Extra FileOption values may be given to control whether things like hidden files, or single (non-sequence) files should be included in the search results.
If there are any errors reading the directory or the files, a non-nil error will be returned.
func ListFiles ¶
func ListFiles(path string) (FileSequences, error)
ListFiles is an alias for FindSequencesOnDisk, passing the SingleFiles option. It. will include all files in the results. Even those that do not contain frame range patterns. It is like an ls, but with collapsed sequences.
func (FileSequences) Len ¶
func (fs FileSequences) Len() int
func (FileSequences) Less ¶
func (fs FileSequences) Less(i, j int) bool
func (FileSequences) Swap ¶
func (fs FileSequences) Swap(i, j int)
type FrameSet ¶
type FrameSet struct {
// contains filtered or unexported fields
}
FrameSet wraps a sequence of frames in container that exposes array-like operations and queries, after parsing the given frame range string.
func NewFrameSet ¶
Create a new FrameSet from a given frame range string Returns an error if the frame range could not be parsed.
func (*FrameSet) Frame ¶
Frame returns the frame number value for a given index into the frame set. If the index is outside the bounds of the frame set range, then an error is returned.
func (*FrameSet) FrameRange ¶
FrameRange returns the range string that was used to initialize the FrameSet
func (*FrameSet) FrameRangePadded ¶
FrameRangePadded returns the range string that was used to initialize the FrameSet, with each number padded out with zeros to a given width
func (*FrameSet) Frames ¶
Frames returns a slice of the frame numbers that were parsed from the original frame range string.
Warning: This allocates a slice containing number of elements equal to the Len() of the range. If the sequence is massive, it could hit slice limits. Better to use IterFrames()
func (*FrameSet) Index ¶
Index returns the index position of the frame value within the frame set. If the given frame does not exist, then return -1
func (*FrameSet) Invert ¶
Invert returns a new FrameSet that represents all frames *not* within the current FrameSet. That is, it will create a range that "fills in" the current one.
func (*FrameSet) InvertedFrameRange ¶
InvertedFrameRange returns a new frame range string that represents all frames *not* within the current FrameSet. That is, it will create a range that "fills in" the current one.
type PadStyle ¶
type PadStyle int
const ( // Constants defining the style of padding to use // when converting between padding characters ('#', '##', '@@@') // and their equivalent numeric padding width PadStyleHash1 PadStyle = 0 // '#' char == 1 PadStyleHash4 PadStyle = 1 // '#' char == 4 PadStyleDefault = PadStyleHash4 )
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
seqls
seqls - list directory contents, rolled up into file sequences
|
seqls - list directory contents, rolled up into file sequences |
cpp
|
|
Package ranges provides objects that can represent simple integer ranges with an optional stepping, as well as complex non-contiguous ranges.
|
Package ranges provides objects that can represent simple integer ranges with an optional stepping, as well as complex non-contiguous ranges. |