Export arbitrary time samples

[jufrantz]

This PR adds a new -timeSample/-ts flag to MayaUSDExportCommand (and the dictionary option on the MPxFileTranslator path), letting users export an explicit, arbitrary list of absolute time samples, regardless of -frameRange/-frameStride/-frameSample.

We need this in some specific export workflows. It mirrors a capability available in Maya's AbcExport plugin, which lets users repeat -frameRange with single-point frameRanges to export isolated samples.

Included Changes

• UsdMayaWriteUtil::GetTimeSamples now takes an optional userTimeSamples vector, merged with the samples computed from frameRange, subframeOffsets and stride, always included even when frameRange is empty. Duplicates are removed before merging, to avoid evaluating/writing the same frame twice.
• Only validate stride when frameRange is actually used, since it has no effect otherwise.
• Add a new timeSample token support to UsdMayaJobExportArgs, mirroring the frameSample token.
• Add -timeSample/-ts flag to MayaUSDExportCommand.
• On the MPxFileTranslator path, the timeSample option is gated by the animation option, matching the frameRange option's behaviour.
• Fix UsdMayaUtil::GetDictionaryFromArgDatabase to handle vector<double> guide type. It was already causing a coding error when -frameSample was used.
• Add unit tests to verify exporting an explicit time-sample list.
• Document the new -timeSample flag in lib/mayaUsd/commands/Readme.md.

[scottrenaud]

Hey @jufrantz!

I discussed it with some folks on the team, there was some debate about whether instead we should improve frame range to support multiple ranges and individual frames ex: [1-10, 15, 18, 20-45], but it's true that individual frames would still get affected by the frameSample offset. So this new parameter would still be a benefit.

However, we're wondering if "timeSample" is the clearest name for the parameter.
Would "explicitFrame" perhaps be more appropriate? Or have you thought of other ideas?

Thanks!
Scott

[jufrantz]

Hi @scottrenaud,

Thanks for your feedback!

Yes, definitely, supporting multiple frame ranges would be more interesting, and it would cover our use case. Having frameSample apply to those extra frames wouldn't be a problem for us either. That said, I'm not sure how to add this cleanly while keeping back-compatibility with the current command syntaxes (frameRange is a single-use float2 today, and making it multi-use would break python callers) and the option dicts and string formats.

For the single-frame parameter, the range specification differs between the command arguments and the options dict/options-string formats:

• maya.cmds.mayaUSDExport has -frameRange flag
• Options dict (mayaUsd.lib.PrimUpdaterManager.mergeToUsd) / options string (used by file-translator / maya.cmds.mayaUSDMergeToUSD): the range is decomposed into startTime/endTime.

Rather than explicitFrame, what would you think of using "extra" prefix, with these names at each level:

• maya.cmds.mayaUSDExport: extraFrame, consistent with its siblings frameRange, frameStride, frameSample.
  e.g. mayaUSDExport(frameRange=(1, 10), extraFrame=[15.5, 16])
• Options dict and the options string: extraTime, matching the existing startTime/endTime used at that layer.
  e.g. mergeToUsd(node, {"startTime": 1, "endTime": 10, "extraTime": [15.5, 16]})

Let me know what you think. Happy to go with explicitFrame/explicitTime too if you prefer this.

Julien