gofileseq: github.com/justinfx/gofileseq Index | Files | Directories

package fileseq

import "github.com/justinfx/gofileseq"

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 Delimted: 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

Package Files

fileseq.go frameset.go pad.go sequence.go

Constants

const Version = "2.3.0"

func FramesToFrameRange Uses

func FramesToFrameRange(frames []int, sorted bool, zfill int) string

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 Uses

func IsFrameRange(frange string) bool

IsFrameRange returns true if the given string is a valid frame range format. Any padding characters, such as '#' and '@' are ignored.

func PadFrameRange Uses

func PadFrameRange(frange string, pad int) string

PadFrameRange takes a frame range string and returns a new range with each number padded out with zeros to a given width

func PaddingChars Uses

func PaddingChars(pad int) string

PaddingChars returns the proper padding characters, given an amount of padding. Uses PadStyleDefault.

type FileOption Uses

type FileOption int

FileOptions indicate how file listings should be performed and returned

const (
    // Include hidden files in file listings
    HiddenFiles FileOption = iota
    // Include paths that aren't detected as sequences, and are
    // just single files
    SingleFiles
    // Set the PadStyle to PadStyleHash1
    FileOptPadStyleHash1
    // Set the PadStyle to PadStyleHash4
    FileOptPadStyleHash4
)

type FileSequence Uses

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 Uses

func FindSequenceOnDisk(pattern string) (*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. 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 FindSequenceOnDiskPad Uses

func FindSequenceOnDiskPad(pattern string, padStyle PadStyle) (*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. 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 Uses

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 Uses

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 Uses

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 Uses

func (s *FileSequence) Copy() *FileSequence

Copy returns a copy of the FileSequence

func (*FileSequence) Dirname Uses

func (s *FileSequence) Dirname() string

Dirname returns the parsed directory component of the sequence string

func (*FileSequence) End Uses

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 Uses

func (s *FileSequence) Ext() string

Ext returns the file extension component from the sequence, including the leading period character.

func (*FileSequence) Format Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (s *FileSequence) SetBasename(base string)

Set a new basename for the sequence

func (*FileSequence) SetDirname Uses

func (s *FileSequence) SetDirname(dir string)

Set a new dirname for the sequence

func (*FileSequence) SetExt Uses

func (s *FileSequence) SetExt(ext string)

Set a new ext for the sequence

func (*FileSequence) SetFrameRange Uses

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 Uses

func (s *FileSequence) SetFrameSet(frameSet *FrameSet)

Set a new FrameSet for the sequence

func (*FileSequence) SetPadding Uses

func (s *FileSequence) SetPadding(padChars string)

Set a new padding characters for the sequence

func (*FileSequence) SetPaddingStyle Uses

func (s *FileSequence) SetPaddingStyle(style PadStyle)

Set a new padding style for mapping between characters and their numeric width

func (*FileSequence) Split Uses

func (s *FileSequence) Split() FileSequences

func (*FileSequence) Start Uses

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 Uses

func (s *FileSequence) String() string

String returns the formatted sequence

func (*FileSequence) ZFill Uses

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 Uses

type FileSequences []*FileSequence

FileSequences is a slice of FileSequence pointers, which can be sorted

func FindSequencesOnDisk Uses

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 Uses

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 Uses

func (fs FileSequences) Len() int

func (FileSequences) Less Uses

func (fs FileSequences) Less(i, j int) bool

func (FileSequences) Swap Uses

func (fs FileSequences) Swap(i, j int)

type FrameSet Uses

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 Uses

func NewFrameSet(frange string) (*FrameSet, error)

Create a new FrameSet from a given frame range string Returns an error if the frame range could not be parsed.

func (*FrameSet) End Uses

func (s *FrameSet) End() int

End returns the last frame in the frame set

func (*FrameSet) Frame Uses

func (s *FrameSet) Frame(index int) (int, error)

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 Uses

func (s *FrameSet) FrameRange() string

FrameRange returns the range string that was used to initialize the FrameSet

func (*FrameSet) FrameRangePadded Uses

func (s *FrameSet) FrameRangePadded(pad int) string

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 Uses

func (s *FrameSet) Frames() []int

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) HasFrame Uses

func (s *FrameSet) HasFrame(frame int) bool

HasFrame returns true if the frameset contains the given frame value.

func (*FrameSet) Index Uses

func (s *FrameSet) Index(frame int) int

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 Uses

func (s *FrameSet) Invert() *FrameSet

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 Uses

func (s *FrameSet) InvertedFrameRange(pad int) string

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.

func (*FrameSet) Len Uses

func (s *FrameSet) Len() int

Len returns the number of frames in the set

func (*FrameSet) Normalize Uses

func (s *FrameSet) Normalize() *FrameSet

Normalize returns a new sorted and compacted FrameSet

func (*FrameSet) Start Uses

func (s *FrameSet) Start() int

Start returns the first frame in the frame set

func (*FrameSet) String Uses

func (s *FrameSet) String() string

String implements Stringer, by returning the frame range string

type PadStyle Uses

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

PathSynopsis
rangesPackage ranges provides objects that can represent simple integer ranges with an optional stepping, as well as complex non-contiguous ranges.

Package fileseq imports 11 packages (graph). Updated 2017-04-18. Refresh now. Tools for package owners.