usdBVHAnimPlugin

String Parsing

Parsing of the BVH file format is built on top of a more general purpose string parsing library provided by Parse.h.

struct Parse

A small class for parsing strings.

Public Functions

inline operator bool() const

Returns true if the Parse object is still valid, or false otherwise. This method can be used to determine whether an error has occurred during parsing (if it has, an invalid Parse object will be returned).

A Parse object is considered valid if it still refers to a string - that is, that its m_Begin and m_End pointers are still valid, and ordered such that m_Begin <= m_End. Note that a Parse object that has successfully reached the end of its input string is considered valid.

inline Parse Char(char value) const

Parse a single character from the string. If that character is matched, a new Parse object is returned beginning at the next character. Otherwise, an invalid Parse object is returned.

inline Parse String(const char *str) const

Parse a sub-string. If the string is matched, a new Parse object is returned beginning at the next character. Otherwise, an invalid Parse object is returned.

inline Parse AnyOf(const char *chars) const

Parse any of the given characters. If any of the characters were matched, a Parse object is returned beginning at the next character. Otherwise, an invalid Parse object is returned.

inline Parse AnyOf(std::initializer_list<std::function<Parse(Parse const&)>> const &args) const

Parse any of the given items, where each item is given as a function that should either return a valid Parse object if successful, or an invalid Parse object if unsuccessful. This function returns as soon as one of the given functions returns a valid Parse object, with this function also returning the valid Parse object.

inline Parse AtLeast(size_t n, std::function<Parse(Parse)> const &function) const

Parse a minimum of the given number of items, where each item is described by a function that should either return a valid Parse object if successful, or an invalid Parse object if unsuccessful.

This function returns a Parse object beginning immediately after the items that were successfully parsed, or an invalid Parse object if the given number of items couldn’t be parsed.

Note that 0 is a valid minimum number of items, and can be used in cases where the given items are entirely optional.

inline Parse Skip(char const *chars) const

Returns a new Parse object that starts immediately after matching any of the given characters, effectively skipping over them.

inline Parse Capture(std::string &result, std::function<Parse(Parse)> const &function) const

Calls the given function with this Parse object given as an argument. The function is expected to attempt to parse some of the input string, and return a new Parse object starting at the remaining portion of the string. This function will return this Parse object, and capture the portion of the string that was parsed to the given result string.

The given function can also be permitted to return an invalid Parse object, in which case, the result string will be emptied and the invalid Parse object will be returned by this function.

Public Members

char const *m_Begin = nullptr

A pointer to the beginning of the input string.

char const *m_End = nullptr

A pointer to the end of the input string.

BVH Structures

The structures that represent a BVH document are defined in ParseBVH.h

enum class usdBVHAnimPlugin::BVHChannel

Enumeration of supported BVH channel types.

Values:

enumerator None

Value used to signify the lack of any BVH channels.

enumerator XPosition

A channel that represents X position.

enumerator YPosition

A channel that represents Y position.

enumerator ZPosition

A channel that represents Z position.

enumerator XRotation

A channel that represents X rotation.

enumerator YRotation

A channel that represents Y rotation.

enumerator ZRotation

A channel that represents Z rotation.

enumerator BitCount

The number of bits required to store a single channel value.

enumerator BitMask

A bit-mask filled with the number of bits required to store a single channel value.

struct BVHOffset

A structure representing a translational joint offset.

Public Members

double m_Translation[3]

An array storing the X/Y/Z components of the joint offset.

struct BVHTransform

A structure representing a joint transform.

Public Members

double m_RotationQuat[4]

An array storing the X/Y/Z/W components of the joint rotation quaternion.

double m_Translation[3]

An array storing the X/Y/Z components of the joint translation.

struct BVHDocument

A structure representing an entire BVH document.

Public Members

std::vector<std::string> m_JointNames

Contains the joint names for each joint in the BVH skeleton.

std::vector<int> m_JointParents

Contains the joint parent indices for each joint in the BVH skeleton.

std::vector<BVHOffset> m_JointOffsets

Contains the translational joint offsets for each joint the BVH skeleton.

std::vector<unsigned int> m_JointNumChannels

Contains the number of animated channels for each joint in the animation.

std::vector<uint32_t> m_JointChannels

Contains a bit-packed array of BVHChannel values for each joint in the animation.

Each element contains 3-bits for each of the joint’s channels (given by m_JointNumChannels), and the value of each 3-bits is one of the BVHChannel enumerated values.

double m_FrameTime

The amount of time in seconds between each frame of the animation.

std::vector<BVHTransform> m_FrameTransforms

The animated joint transforms packed into a single vector, ordered first by frame number, then by joint, then by joint channel (given by m_JointChannels).

e.g.

• Frame 0 - Joint 0 - Channel 0

• Frame 0 - Joint 0 - Channel 1

• Frame 0 - Joint 1 - Channel 0

• Frame 1 - Joint 0 - Channel 0

• Frame 1 - Joint 0 - Channel 1

• Frame 1 - Joint 1 - Channel 0

• …

Public Static Attributes

static int c_RootParentIndex = -1

A parent index value used for root-level bones, which do not have parents.

BVH Parsing

The entry points for parsing are defined in ParseBVH.h:

bool usdBVHAnimPlugin::ParseBVH(std::string const &filePath, BVHDocument &result)

Parse a BVH file at the given file path, and store the result in the given BVHDocument structure. Returns true on success, or false on failure.

bool usdBVHAnimPlugin::ParseBVH(std::istream &stream, BVHDocument &result)

Parse a BVH file whose contents is in the given stream, and store the result in the given BVHDocument structure. Returns true on success, or false on failure.

Parsing is implemented in ParseBVH.cpp.

USD File Format Plug-in

The plug-in itself is implemented in BvhFileFormat.cpp, in which the BvhFileFormat class implements SdfFileFormat for the BVH file format. This class has only implemented the reading functionality for BVH files - writing BVH files is not currently supported.

Also note that currently, the entire file is translated and cached in memory at the time the file is opened. BVH data is not currently lazily loaded (e.g. SdfAbstractData is not currently implemented for BVH data).

class BvhFileFormat : public SdfFileFormat

An SdfFileFormat for BVH animation data, transcoding the BVH data into usdSkel prims.

Public Functions

bool CanRead(std::string const &filePath) const override

Returns true if the given file path can be read by this plug-in or false otherwise.

bool Read(SdfLayer *layer, std::string const &resolvedPath, bool metadataOnly) const override

Reads the given BVH file into the given SdfLayer. Returns true on success or false on failure.

inline bool WriteToString(SdfLayer const &layer, std::string *str, std::string const &comment) const override

This function always returns false. Only reading of BVH files is supported.

inline bool WriteToStream(SdfSpecHandle const &spec, std::ostream &out, size_t indent) const override

This function always returns false. Only reading of BVH files is supported.