Split pybind declarations and definitions

[timohl]

Type

• Bug fix (non-breaking change which fixes an issue): Fixes C++ Types in Python Documentation #6867
• New feature (non-breaking change which adds functionality). Resolves #
• Breaking change (fix or feature that would cause existing functionality to not work as expected) Resolves #

Motivation and Context

As explained in #6867 there are several instances where C++ types are shown in the Python binding documentation.
Some of those instances can be solved by splitting the py::_class and py::enum_ declarations from the method/function definitions using .def(...).
This ensures, that all types are properly declared before usage.

Checklist:

• I have run python util/check_style.py --apply to apply Open3D code style
  to my code.
• This PR changes Open3D behavior or adds new functionality.
  • Both C++ (Doxygen) and Python (Sphinx / Google style) documentation is
    updated accordingly.
  • I have added or updated C++ and / or Python unit tests OR included test
    results (e.g. screenshots or numbers) here.
• I will follow up and update the code if CI fails.
• For fork PRs, I have selected Allow edits from maintainers.

Description

Split modules:

• camera
• core
• data (no changes needed)
• geometry
• io
• ml
• pipelines
• t
• utility
• visualization

Style+Testing:

• Applied style checker
• Run testing
• Add changelog entry

[update-docs]

Thanks for submitting this pull request! The maintainers of this repository would appreciate if you could update the CHANGELOG.md based on your changes.

[timohl]

All except for o3d.data is done now!
I don't think splitting o3d.data is necessary, since nothing else depends on it, and it just contains a lot of small classes.

This removes 80 C++ types from python binding docs, if I see correctly.
Here you can see the before vs after diff of the output of pybind11-stubgen open3d:
The 11 additions are just changing object addresses, so they can be subtracted from the deletions.

Sorry for the huge number of changes required for this, but it is basically just a lot of movement of code.
In order to make review easier, here is a summary of how I split modules up into declarations and definitions, with examples from o3d.camera:

Declarations contain py::module, py::class_ and py::enum_ declarations, as well as the value declarations of an enum:

py::module m_camera = m.def_submodule("camera");
py::class_<PinholeCameraIntrinsic> pinhole_intr(
        m_camera, "PinholeCameraIntrinsic", "<docs...>");
py::enum_<PinholeCameraIntrinsicParameters> pinhole_intr_params(
            m_camera, "PinholeCameraIntrinsicParameters", py::arithmetic(),
            "PinholeCameraIntrinsicParameters");
pinhole_intr_params
            .value("PrimeSenseDefault",
                   PinholeCameraIntrinsicParameters::PrimeSenseDefault,
                   "Default camera intrinsic parameter for PrimeSense.")
...

Definitions refer to modules and classes using .attr() and add method and function definitions to them:

auto m_camera = static_cast<py::module>(m.attr("camera"));
// open3d.camera.PinholeCameraIntrinsic
auto pinhole_intr = static_cast<py::class_<PinholeCameraIntrinsic>>(
        m_camera.attr("PinholeCameraIntrinsic"));
py::detail::bind_default_constructor<PinholeCameraIntrinsic>(pinhole_intr);
py::detail::bind_copy_functions<PinholeCameraIntrinsic>(pinhole_intr);
pinhole_intr
        .def(py::init<int, int, const Eigen::Matrix3d>(), "width"_a,
             "height"_a, "intrinsic_matrix"_a)

Next steps for me will be running style checks and unit tests.
Please let me know if you have any questions for review, if I missed anything, or anything else I should do?
I would like to further improve the documentation and typing stubs generated by pybind11-stubgen after this.

[timohl]

Applied style checker, run tests on my machine (no extra flags though like CUDA, ...), and added entry to changelog.
Codacy Static Code Analysis fails with two new issues, however looking into it, they existed before but just got shifted.

Please tell me if any action is required on my part or any open questions come up.

[timohl]

Failed checks:

• Codacy Static Code Analysis: probably false positive and only shown as new because code moved location.
• windows (ON, OFF, ON, Debug): Unrelated issue/Fails also in main
• ubuntu-sycl (ON): Unrelated issue/Fails also in main
• ubuntu-sycl (OFF): Unrelated issue/Fails also in main

All other checks were successful.

[ssheorey]

Thanks @timohl for this huge effort! This looks like a pretty useful update. I'll check it out. Can you paste some before and after screenshots of how the docs look better after this PR, and how a code editor is able to better do auto-complete with pybind11-stubgen (e.g. VS code or your favourite editor).

[ssheorey]

PS: Also please consider contributing the script for pybind11-stubgen, so that other users can get auto-complete out of the box for Open3D.

[timohl]

Here how this changes vscode type checking ability in three cases:

• No generated typing stubs (No stubs)
• Generated typing stubs from main (old stubs)
• Generated typing stubs from this pull request (new stubs)

Typing stubs where generated using pybind11-stubgen open3d -o typings.

Desc.	Image
No stubs: The hover box provides no documentation. Types are not recognized.
Old stubs: The hover box provides documentation and partial typing. Return type is .... Notice how get_center() at the bottom is gray, since the type checker does not know the type of oriented_bb
New stubs: The hover box provides documentation and full typing. Return type is properly recognized. get_center() is yellow, since the type checker knows the type of oriented_bb.

[ssheorey]

Thanks @timohl Looks good.

Next step: Package the generated stubs with Open3D.