[feat] Add PyNvBatchAsyncStreamReader for 2D batched async stream dec…

[xupinjie]

Description

Introduces a new async-only video decoder under accvlab.on_demand_video_decoder that decodes V videos × F frames per video in a single in-flight async submission, returning List[List[RGBFrame]] indexed [v][f]. Targeted at StreamPETR-like workloads consuming multi-sweep batches per training step.

Type of Change

Please select (at least one):

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation / examples / tutorials / demos
• Supporting functionality change (fix or feature in documentation generation, helper scripts, ...)
• Refactoring / internal change
• Other (please describe):

Testing

Checklist for testing:

• Tests added or updated if/as needed
• Repository test runner executed: scripts/run_tests.sh

Optionally, add a brief description.

Documentation, Examples, Tutorials, Demos

Checklist for documentation:

• User-facing documentation updated if/as needed (including API docs)
• Examples / tutorials / demos updated or added (if relevant)
• Limitations and constraints documented (if relevant)
• Performance documented (if relevant)
• Documentation building successful & checks outlined in the Documentation Checks section of the Contribution Guide are performed

Optionally, add a brief description.

Code Quality

Checklist for dependencies:

• Dependencies updated in the relevant pyproject.toml if/as needed
• Code formatted according to the Code Formatting Guide

Optionally, add a brief description.

Related Issues / Context

If applicable, link related issues, discussions etc.

---

DCO / Sign-Off

Please refer to the section on Signing Your Work & Developer Certificate of Origin (DCO)
in the Contribution Guide before submitting your contribution.

References

For additional details, please refer to the Contribution Guide.
The following guides are available (referenced in the Contribution Guide for further details):

• docs/guides/CONTRIBUTION_GUIDE.md
• docs/guides/DEVELOPMENT_GUIDE.md
• docs/guides/DOCUMENTATION_SETUP_GUIDE.md
• docs/guides/FORMATTING_GUIDE.md

Please also refer to the summary checklist in the Contribution Guide,
which is a guideline for what to consider when submitting your contribution and covers the same topics as the checklists above.

[RmSchaffert]

Thank you!
I added some inline comments in the code. Please have a look.

[RmSchaffert]

It may be good to mention that the file list remains the same (i.e. a flat list with one file name per camera) for both methods. Although this is already implied by the description above, I think it may help with understanding.

[RmSchaffert]

Does this improve performance or is it "just" a convenience feature? It may be good to add a short note on that as especially the third point in the list below seems to indicate that this is a convenience feature.

[RmSchaffert]

Nitpick: I would say "Skipping the clone [leads to]" instead of "[is]"

[RmSchaffert]

Please consider making PyNvBatchAsyncStreamReader a reference (link) to allow for easy navigation when reading the docs.

[RmSchaffert]

Maybe remove the "is unchanged" formulation, as this refers to a prior version instead of describing the current state.

[RmSchaffert]

Should release_device_memory and release_decoder be in camel case? The other methods are in upper camel case. However, I see that other decoders have some methods in snake case. Are these methods special?

[RmSchaffert]

Is this still needed? As the implementation is already available, it may be better to remove this to avoid unneeded complexity in the code.

[RmSchaffert]

Absolute paths (w.r.t. the local file system) would still break.
Maybe something like:

For directives inside Python docstrings rendered by autodoc:
1. Find the docs file that renders the docstring, usually `packages/<pkg>/docs/api*.rst`.
2. Resolve directive paths from that docs file, not from the Python source file.
3. Prefer files under `packages/<pkg>/docs/`, e.g. `.. image:: images/foo.png`.
4. For package-root sibling dirs listed in `docu_referenced_dirs.txt`, use paths from `docs/`, e.g. `.. literalinclude:: ../example/foo.py`.
5. Never use machine-local absolute filesystem paths such as `/home/user/...`.

[RmSchaffert]

Nitpick: In the best case, the edit would actually be done to the original file (as symlinks are used). Maybe say something like:

In the best case, this would work accidentally (due to symlink behavior), but in the worst case, ...

[RmSchaffert]

It may be good to mention in the description that for each V, the same number of frames must be used.