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

[Copilot]

Pull request overview

Adds explicit arbitrary time-sample support to Maya USD export paths.

Changes:

• Adds -timeSample/-ts and dictionary-option handling.
• Merges, sorts, and deduplicates explicit and generated samples.
• Adds documentation and integration tests.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/lib/usd/translators/testUsdExportExplicitTimeSamples.py	Tests explicit sample export paths.
test/lib/usd/translators/CMakeLists.txt	Registers the new tests.
lib/mayaUsd/utils/util.cpp	Parses multi-use double flags.
lib/mayaUsd/fileio/utils/writeUtil.h	Extends the time-sampling API.
lib/mayaUsd/fileio/utils/writeUtil.cpp	Merges explicit samples.
lib/mayaUsd/fileio/jobs/jobArgs.h	Declares the new option token.
lib/mayaUsd/fileio/jobs/jobArgs.cpp	Handles dictionary-based samples.
lib/mayaUsd/commands/Readme.md	Documents the new flag.
lib/mayaUsd/commands/baseExportCommand.h	Defines flag names.
lib/mayaUsd/commands/baseExportCommand.cpp	Parses and applies the flag.

Suppressed comments (1)

test/lib/usd/translators/testUsdExportExplicitTimeSamples.py:75

• This second dictionary union also requires Python 3.9 and prevents the file-translator tests from running under the supported Python 3.7 configuration (doc/build.md:16). Use copy() plus update() here as well.

        exportOptions = kwargs | dict(
            mergeTransformAndShape=True,
            chaser=f'[{_FrameLoggingChaser.name}]'
        )

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[AramAzhari-adsk]

@seando-adsk is this a valid concern? Are we still supporting Python 3.7 ?

[jufrantz]

@AramAzhari-adsk just in case, I made this code 3.7 compatible (e029305)

[seando-adsk]

No, we have dropped py 3.7 and 3.9. The min we need to support is 3.10 for Maya 2024.

[scottrenaud]

I see there's some activity, just wanted to reply and say "extraFrame" and "extraTime" sounds good to me as a label switch @jufrantz!