fileseq

package module
v2.6.1+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 3, 2018 License: MIT Imports: 11 Imported by: 6

README

Fileseq

Go project version GoDoc Travis Build Status Go Report

A Go language library for parsing file sequence strings commonly used in VFX and animation applications.

Ported from the original fileseq Python library: https://github.com/sqlboy/fileseq

For C++, see C++ Support

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

Sequence Formats

Sequences of files are expected to follow a pattern similar to:

  • /path/to/some/file_foo.0100.exr
  • /path/to/some/file_foo.1-100#.jpg
  • /path/to/some/file_foo.1-100@@@.tif

Install

go get github.com/justinfx/gofileseq

Also included is a seqls tool, which uses gofileseq to produce an executable, used for listing sequences on the filesystem:

And seqinfo tool, which can print plain-text or json parsed information about one or more sequence strings.

Download the latest binary release

Or install from source:

go get github.com/justinfx/gofileseq/cmd/seqls
seql some/images
# some/images/file_foo.1-100@@@.tif

C++ Support

A C++ pure port of gofileseq is also available in the cpp dir

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

View Source 
const Version = "2.6.1"

Variables

This section is empty.

Functions

func FramesToFrameRange 

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 

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 

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 

func PaddingChars(pad int) string

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 

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 

func (s *FrameSet) End() int

End returns the last frame in the frame set

func (*FrameSet) Frame 

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 

func (s *FrameSet) FrameRange() string

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

func (*FrameSet) FrameRangePadded 

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 

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 

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

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

func (*FrameSet) Index 

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 

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 

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 

func (s *FrameSet) Len() int

Len returns the number of frames in the set

func (*FrameSet) Normalize 

func (s *FrameSet) Normalize() *FrameSet

Normalize returns a new sorted and compacted FrameSet

func (*FrameSet) Start 

func (s *FrameSet) Start() int

Start returns the first frame in the frame set

func (*FrameSet) String 

func (s *FrameSet) String() string

String implements Stringer, by returning the frame range string

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
)

Source Files

View all Source files

Directories

Path Synopsis
cmd
seqinfo
seqls
seqls - list directory contents, rolled up into file sequences
 seqls - list directory contents, rolled up into file sequences
exp
cpp/export
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.