Docstrings for PyMaterialXRender. (#1567)

Signed-off-by: Stefan Habel <19556655+StefanHabel@users.noreply.github.com>

source/PyMaterialX/PyMaterialXRender/PyCamera.cpp

@@ -13,24 +13,124 @@ namespace mx = MaterialX;
 void bindPyCamera(py::module& mod)
 {
     py::class_<mx::Camera, mx::CameraPtr>(mod, "Camera")
-        .def_static("create", &mx::Camera::create)
-        .def("setWorldMatrix", &mx::Camera::setWorldMatrix)
-        .def("getWorldMatrix", &mx::Camera::getWorldMatrix)
-        .def("setViewMatrix", &mx::Camera::setViewMatrix)
-        .def("getViewMatrix", &mx::Camera::getViewMatrix)
-        .def("setProjectionMatrix", &mx::Camera::setProjectionMatrix)
-        .def("getProjectionMatrix", &mx::Camera::getProjectionMatrix)
-        .def("getWorldViewProjMatrix", &mx::Camera::getWorldViewProjMatrix)
-        .def("getViewPosition", &mx::Camera::getViewPosition)
-        .def("getViewDirection", &mx::Camera::getViewDirection)
-        .def("setViewportSize", &mx::Camera::setViewportSize)
-        .def("getViewportSize", &mx::Camera::getViewportSize)
-        .def("projectToViewport", &mx::Camera::projectToViewport)
-        .def("unprojectFromViewport", &mx::Camera::unprojectFromViewport)
-        .def_static("createViewMatrix", &mx::Camera::createViewMatrix)
-        .def_static("createPerspectiveMatrix", &mx::Camera::createPerspectiveMatrix)
-        .def_static("createOrthographicMatrix", &mx::Camera::createOrthographicMatrix)
-        .def_static("transformPointPerspective", &mx::Camera::transformPointPerspective)
+
+        .def_static("create", &mx::Camera::create,
+                    PYMATERIALX_DOCSTRING(R"docstring(
+    Create an instance of this class.
+)docstring"))
+
+        .def("setWorldMatrix", &mx::Camera::setWorldMatrix,
+             py::arg("mat"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Set the world matrix.
+)docstring"))
+
+        .def("getWorldMatrix", &mx::Camera::getWorldMatrix,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return the world matrix.
+)docstring"))
+
+        .def("setViewMatrix", &mx::Camera::setViewMatrix,
+             py::arg("mat"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Set the view matrix.
+)docstring"))
+
+        .def("getViewMatrix", &mx::Camera::getViewMatrix,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return the view matrix.
+)docstring"))
+
+        .def("setProjectionMatrix", &mx::Camera::setProjectionMatrix,
+             py::arg("mat"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Set the projection matrix.
+)docstring"))
+
+        .def("getProjectionMatrix", &mx::Camera::getProjectionMatrix,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return the projection matrix.
+)docstring"))
+
+        .def("getWorldViewProjMatrix", &mx::Camera::getWorldViewProjMatrix,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Compute our full model-view-projection matrix.
+)docstring"))
+
+        .def("getViewPosition", &mx::Camera::getViewPosition,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Derive viewer position from the view matrix.
+)docstring"))
+
+        .def("getViewDirection", &mx::Camera::getViewDirection,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Derive viewer direction from the view matrix.
+)docstring"))
+
+        .def("setViewportSize", &mx::Camera::setViewportSize,
+             py::arg("size"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Set the size of the viewport window.
+)docstring"))
+
+        .def("getViewportSize", &mx::Camera::getViewportSize,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return the size of the viewport window.
+)docstring"))
+
+        .def("projectToViewport", &mx::Camera::projectToViewport,
+             py::arg("v"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Project a position from object to viewport space.
+)docstring"))
+
+        .def("unprojectFromViewport", &mx::Camera::unprojectFromViewport,
+             py::arg("v"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Unproject a position from viewport to object space.
+)docstring"))
+
+        .def_static("createViewMatrix", &mx::Camera::createViewMatrix,
+                    py::arg("eye"),
+                    py::arg("target"),
+                    py::arg("up"),
+                    PYMATERIALX_DOCSTRING(R"docstring(
+    Create a view matrix given an `eye` position, a `target` position, and an
+    `up` vector.
+)docstring"))
+
+        .def_static("createPerspectiveMatrix", &mx::Camera::createPerspectiveMatrix,
+                    py::arg("left"),
+                    py::arg("right"),
+                    py::arg("bottom"),
+                    py::arg("top"),
+                    py::arg("nearP"),
+                    py::arg("farP"),
+                    PYMATERIALX_DOCSTRING(R"docstring(
+    Create a perpective projection matrix given a set of clip planes with
+    `[-1, 1]` projected Z.
+)docstring"))
+
+        .def_static("createOrthographicMatrix", &mx::Camera::createOrthographicMatrix,
+                    py::arg("left"),
+                    py::arg("right"),
+                    py::arg("bottom"),
+                    py::arg("top"),
+                    py::arg("nearP"),
+                    py::arg("farP"),
+                    PYMATERIALX_DOCSTRING(R"docstring(
+    Create an orthographic projection matrix given a set of clip planes with
+    `[-1, 1]` projected Z.
+)docstring"))
+
+        .def_static("transformPointPerspective", &mx::Camera::transformPointPerspective,
+                    py::arg("m"),
+                    py::arg("v"),
+                    PYMATERIALX_DOCSTRING(R"docstring(
+    Apply a perspective transform to the given 3D point, performing a
+    homogeneous divide on the transformed result.
+)docstring"))
+
         .doc() = PYMATERIALX_DOCSTRING(R"docstring(
     A simple camera class, supporting transform matrices and arcball
     functionality for object-viewing applications.

source/PyMaterialX/PyMaterialXRender/PyCgltfLoader.cpp

@@ -12,9 +12,33 @@ namespace mx = MaterialX;
 void bindPyCgltfLoader(py::module& mod)
 {
     py::class_<mx::CgltfLoader, mx::CgltfLoaderPtr, mx::GeometryLoader>(mod, "CgltfLoader")
-        .def_static("create", &mx::CgltfLoader::create)
-        .def(py::init<>())
-        .def("load", &mx::CgltfLoader::load)
+
+        .def_static("create", &mx::CgltfLoader::create,
+                    PYMATERIALX_DOCSTRING(R"docstring(
+    Create a new cgltf loader.
+)docstring"))
+
+        .def(py::init<>(),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Initialize an instance of this class.
+)docstring"))
+
+        .def("load", &mx::CgltfLoader::load,
+             py::arg("filePath"),
+             py::arg("meshFlip"),
+             py::arg("texcoordVerticalFlip") = false,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Load geometry from disk.
+
+    :param filePath: Path to file to load.
+    :type filePath: FilePath
+    :param meshList: List of meshes to update.
+    :type meshList: List[Mesh]
+    :param texcoordVerticalFlip: Flip texture coordinates in V when loading.
+    :type texcoordVerticalFlip: bool
+    :returns: `True` if load was successful.
+)docstring"))
+
         .doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Wrapper class for a geometry loader to read glTF files using the cgltf
     library.

source/PyMaterialX/PyMaterialXRender/PyGeometryHandler.cpp

@@ -34,9 +34,35 @@ class PyGeometryLoader : public mx::GeometryLoader
 void bindPyGeometryHandler(py::module& mod)
 {
     py::class_<mx::GeometryLoader, PyGeometryLoader, mx::GeometryLoaderPtr>(mod, "GeometryLoader")
-        .def(py::init<>())
-        .def("supportedExtensions", &mx::GeometryLoader::supportedExtensions)
-        .def("load", &mx::GeometryLoader::load)
+
+        .def(py::init<>(),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Initialize an instance of this class.
+)docstring"))
+
+        .def("supportedExtensions", &mx::GeometryLoader::supportedExtensions,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return a set of extensions supported by the loader.
+)docstring"))
+
+        .def("load", &mx::GeometryLoader::load,
+             py::arg("filePath"),
+             py::arg("meshList"),
+             py::arg("texcoordVerticalFlip") = false,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Load geometry from disk.
+
+    This method must be implemented by derived classes.
+
+    :param filePath: Path to file to load.
+    :type filePath: FilePath
+    :param meshList: List of meshes to update.
+    :type meshList: List[Mesh]
+    :param texcoordVerticalFlip: Flip texture coordinates in V when loading.
+    :type texcoordVerticalFlip: bool
+    :returns: `True` if load was successful.
+)docstring"))
+
         .doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Base class representing a geometry loader.
 
@@ -46,17 +72,80 @@ void bindPyGeometryHandler(py::module& mod)
 )docstring");
 
     py::class_<mx::GeometryHandler, mx::GeometryHandlerPtr>(mod, "GeometryHandler")
-        .def(py::init<>())
-        .def_static("create", &mx::GeometryHandler::create)
-        .def("addLoader", &mx::GeometryHandler::addLoader)
-        .def("clearGeometry", &mx::GeometryHandler::clearGeometry)
-        .def("hasGeometry", &mx::GeometryHandler::hasGeometry)
-        .def("getGeometry", &mx::GeometryHandler::getGeometry)
-        .def("loadGeometry", &mx::GeometryHandler::loadGeometry)
-        .def("getMeshes", &mx::GeometryHandler::getMeshes)
-        .def("findParentMesh", &mx::GeometryHandler::findParentMesh)
-        .def("getMinimumBounds", &mx::GeometryHandler::getMinimumBounds)
-        .def("getMaximumBounds", &mx::GeometryHandler::getMaximumBounds)
+
+        .def(py::init<>(),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Initialize an instance of this class.
+)docstring"))
+
+        .def_static("create", &mx::GeometryHandler::create,
+                    PYMATERIALX_DOCSTRING(R"docstring(
+    Create an instance of this class.
+)docstring"))
+
+        .def("addLoader", &mx::GeometryHandler::addLoader,
+             py::arg("loader"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Add a geometry loader.
+
+    :param loader: Loader to add to list of available loaders.
+    :type loader: GeometryLoader
+)docstring"))
+
+        .def("clearGeometry", &mx::GeometryHandler::clearGeometry,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Clear all loaded geometry.
+)docstring"))
+
+        .def("hasGeometry", &mx::GeometryHandler::hasGeometry,
+             py::arg("location"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Determine if any meshes have been loaded from a given `location`.
+)docstring"))
+
+        .def("getGeometry", &mx::GeometryHandler::getGeometry,
+             py::arg("meshes"),
+             py::arg("location"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Find all meshes loaded from a given `location`.
+)docstring"))
+
+        .def("loadGeometry", &mx::GeometryHandler::loadGeometry,
+             py::arg("filePath"),
+             py::arg("texcoordVerticalFlip") = false,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Load geometry from a given location.
+
+    :param filePath: Path to geometry.
+    :type filePath: FilePath
+    :param texcoordVerticalFlip: Flip texture coordinates in V. Default is to
+        not flip.
+    :type texcoordVerticalFlip: bool
+)docstring"))
+
+        .def("getMeshes", &mx::GeometryHandler::getMeshes,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return list of meshes.
+)docstring"))
+
+        .def("findParentMesh", &mx::GeometryHandler::findParentMesh,
+             py::arg("part"),
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return the first mesh in our list containing the given partition.
+
+    If no matching mesh is found, then `None` is returned.
+)docstring"))
+
+        .def("getMinimumBounds", &mx::GeometryHandler::getMinimumBounds,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return the minimum bounds for all meshes.
+)docstring"))
+
+        .def("getMaximumBounds", &mx::GeometryHandler::getMaximumBounds,
+             PYMATERIALX_DOCSTRING(R"docstring(
+    Return the maximum bounds for all meshes.
+)docstring"))
+
         .doc() = PYMATERIALX_DOCSTRING(R"docstring(
     Class which holds a set of geometry loaders.