Fixing the missing methods in Python documention. (#51)

New Features
- The missing methods for a variety of classes have been added to the python docs
- The version of pybind11 has been bumped to the latest release

Signed-off-by: Matthew A Johnson <matjoh@microsoft.com>

.github/workflows/linux.yml

@@ -43,7 +43,7 @@ jobs:
 
       - name: Python build
         run: |
-          pip install --use-deprecated=legacy-resolver -e .[dev]
+          pip install -e .[dev]
           python setup.py develop
 
       - name: Python test

.github/workflows/mac.yml

@@ -43,7 +43,7 @@ jobs:
 
       - name: Python build
         run: |
-          pip install --use-deprecated=legacy-resolver -e .[dev]
+          pip install -e .[dev]
           python setup.py develop
 
       - name: Python test

.github/workflows/windows.yml

@@ -18,11 +18,7 @@ jobs:
   WindowsPython:
     strategy:
       matrix:
-        python_version: ["3.8", "3.9"]
-        python_arch: [x86, x64]
-        include:
-          - python_version: "3.10"
-            python_arch: x64
+        python_version: ["3.8", "3.9", "3.10"]
 
     runs-on: ${{inputs.vmImage}}
 
@@ -34,7 +30,7 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{matrix.python_version}}
-          architecture: ${{matrix.python_arch}}
+          architecture: x64
 
       - name: Get dependencies
         run: |
@@ -51,7 +47,7 @@ jobs:
 
       - name: Python build
         run: |
-          pip install --use-deprecated=legacy-resolver -e .[dev]
+          pip install -e .[dev]
           python setup.py develop
 
       - name: Python test

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [2022-11-03 - Version 1.0.15](https://github.com/microsoft/scenepic/releases/tag/v1.0.15)
+Point release fixing the missing methods in Python documention.
+
+New Features
+- The missing methods for a variety of classes have been added to the python docs
+- The version of pybind11 has been bumped to the latest release
+
 ## [2022-09-07 - Version 1.0.14](https://github.com/microsoft/scenepic/releases/tag/v1.0.14)
 Point release adding additional graph features.
 

CMakeLists.txt

@@ -95,7 +95,7 @@ FetchContent_Declare(
 FetchContent_Declare(
   pybind11
   GIT_REPOSITORY https://github.com/pybind/pybind11/
-  GIT_TAG        479e9a50f38cfa8e525a697d7f5d850f851223b5 # includes fix for pybind/pybind11#4038
+  GIT_TAG        v2.10.1
 )
 
 set(CMAKE_POLICY_DEFAULT_CMP0077 NEW) 

RELEASE_NOTES

@@ -1,7 +1,5 @@
-Point release adding additional graph features.
+Point release fixing the missing methods in Python documention.
 
-New Features:
-- Can specify text alignment and size for graph labels and values
-- Can add vertical rules to separate out horizontal regions of the graph
-- `save_html` can now separate out the script and library components
-  (for easier testing of new Typescript library features)
+New Features
+- The missing methods for a variety of classes have been added to the python docs
+- The version of pybind11 has been bumped to the latest release

VERSION

@@ -1 +1 @@
-1.0.14
+1.0.15

ci/download_deps.py

@@ -7,7 +7,7 @@ import zipfile
 import requests
 
 
-DOXYGEN = "https://www.doxygen.nl/files/doxygen-1.9.3.windows.x64.bin.zip"
+DOXYGEN = "https://www.doxygen.nl/files/doxygen-1.9.5.windows.x64.bin.zip"
 
 
 def _download_and_unzip(download_uri, name, output_dir="."):

docs/source/api.rst

@@ -12,6 +12,7 @@ Scene
 
 .. autoclass:: Scene
     :members:
+    :exclude-members: create_mesh_, simulate_key_presses_, link_canvas_events_
 
 3D Graphics
 -----------

docs/source/conf.py

@@ -22,7 +22,7 @@ copyright = "2021, Microsoft"
 author = "ScenePic Team"
 
 # The full version, including alpha/beta/rc tags
-release = "1.0.14"
+release = "1.0.15"
 
 
 # -- General configuration ---------------------------------------------------

docs/source/graphics2d.rst

@@ -7,13 +7,14 @@ Canvas2D
 
 .. autoclass:: Canvas2D
     :members:
+    :exclude-members: set_layer_settings_
 
 Frame2D
 -------
 
 .. autoclass:: Frame2D
     :members:
-    :exclude-members: add_circle_
+    :exclude-members: add_circle_, add_image_, add_text_
 
 Graph
 -----

docs/source/graphics3d.rst

@@ -7,12 +7,14 @@ Canvas3D
 
 .. autoclass:: Canvas3D
     :members:
+    :exclude-members: set_layer_settings_, create_frame_
 
 Frame3D
 -------
 
 .. autoclass:: Frame3D
     :members:
+    :exclude-members: set_layer_settings_, add_meshes_, add_mesh_
 
 
 Mesh
@@ -28,7 +30,7 @@ MeshUpdate
 
 .. autoclass:: MeshUpdate
     :members:
-    :exclude-members: get_vertex_buffer
+    :exclude-members: get_vertex_buffer, quantize_, difference_range_
 
 MeshInfo
 --------

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "scenepic",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "scenepic",
-      "version": "1.0.14",
+      "version": "1.0.15",
       "license": "MIT",
       "dependencies": {
         "npm": "^8.18.0"

package.json

@@ -1,7 +1,7 @@
 {
   "_comment0": "This file is used by npm to specify the project and npm dependencies",
   "name": "scenepic",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "3D Visualization Made Easy",
   "author": "ScenePic Team",
   "license": "MIT",

pipelines/templates/build-and-test-python.yml

@@ -1,6 +1,6 @@
 steps:
 - bash: |
-    pip install --use-deprecated=legacy-resolver -e .[dev]
+    pip install -e .[dev]
     python setup.py bdist_wheel
   displayName: 'Build wheel'
 

src/scenepic/audio_track.py

@@ -20,4 +20,12 @@ def _data_set(self, data):
 
 
 AudioTrack.load_from_buffer = load_from_buffer
-AudioTrack.data = property(_data_get, _data_set)
+AudioTrack.load_from_buffer.__doc__ = """Load audio from a pre-existing data buffer and extension.
+
+Args:
+    self (AudioTrack): self reference
+    data (bytes): the binary data for the audio
+    ext (str): the file extension (e.g. mp3, ogg, wav)
+"""
+
+AudioTrack.data = property(_data_get, _data_set, doc="""The binary audio data.""")

src/scenepic/canvas2d.py

@@ -24,3 +24,16 @@ def set_layer_settings(self, layer_settings: Mapping[str, Union[dict, LayerSetti
 
 
 Canvas2D.set_layer_settings = set_layer_settings
+Canvas2D.set_layer_settings.__doc__ = """Specify the visibilities and opacities of certain mesh layers.
+
+Description:
+    Each Mesh object can optionally be part of a user-identified layer
+    (see Mesh constructor).
+    Calling set_layer_settings will result in an additional drop-down
+    selector in the ScenePic user interface.
+
+Args:
+    self (Canvas2D): the self reference
+    layer_settings (Mapping[str, Union[dict, LayerSettings]]): a mapping from
+        layer IDs to layer settings.
+"""

src/scenepic/canvas3d.py

@@ -53,4 +53,32 @@ def set_layer_settings(self, layer_settings: Mapping[str, Union[dict, LayerSetti
 
 
 Canvas3D.create_frame = create_frame
+Canvas3D.create_frame.__doc__ = """Creates a new Frame3D object and appends to the list of Frame3Ds in the Canvas3D.
+
+Args:
+    frame_id (str): a unique identifier for the Frame3D (will be
+                    automatically populated if not provided).
+    focus_point (FocusPoint): optional 3D focus point for this frame (with optional 3D
+                            rotation for orientation lock), used in the ScenePic user interface.
+    meshes (List[Union[Mesh, MeshUpdate, str]]): optionally pre-populate this Frame3D
+                                                with a set of Meshes, for convenience.
+    camera (Camera): optionally set a camera for this frame
+
+Returns:
+    Frame3D: a new Frame3D object
+"""
+
 Canvas3D.set_layer_settings = set_layer_settings
+Canvas3D.set_layer_settings.__doc__ = """Specify the visibilities and opacities of certain mesh layers.
+
+Description:
+    Each Mesh object can optionally be part of a user-identified layer
+    (see Mesh constructor).
+    Calling set_layer_settings will result in an additional drop-down
+    selector in the ScenePic user interface.
+
+Args:
+    self (Canvas3D): the self reference
+    layer_settings (Mapping[str, Union[dict, LayerSettings]]): a LayerSettings object
+        or a dictionary. See LayerSettings for details.
+"""

src/scenepic/frame2d.py

@@ -50,5 +50,43 @@ def add_text(self, text: str, left: float, bottom: float,
 
 
 Frame2D.add_image = add_image
+Frame2D.add_image.__doc__ = """Add an image to the frame.
+
+Args:
+    self (Frame2D): the self reference
+    image_id (str): the unique identifier of the image
+    position_type (str, optional): one of "fit", "fill", "stretch", or "manual". Defaults to "fit".
+    x (float, optional): x coordinate to draw image at if position_type == "manual". Defaults to 0.0.
+    y (float, optional): y coordinate to draw image at if position_type == "manual". Defaults to 0.0.
+    scale (float, optional): scale factor to draw image by if position_type == "manual". Defaults to 1.0.
+    smoothed (bool, optional): whether to draw an image with smoothing or using nearest neighbor. Defaults to False.
+    layer_id (str, optional): Unique ID of the layer associated with this primitive. Defaults to "".
+"""
+
 Frame2D.add_circle = add_circle
+Frame2D.add_circle.__doc__ = """Add a circle to the frame.
+
+Args:
+    self (Frame2D): the self reference
+    x (float): the center x coordinate
+    y (float): the center y coordinate
+    radius (float): the radius of the circle
+    line_color (np.ndarray, optional): the color of the line. Defaults to Black.
+    line_width (float, optional): the width of the line. Defaults to 1.0.
+    fill_color (np.ndarray, optional): the fill color to use. Defaults to None.
+    layer_id (str, optional): Unique ID of the layer associated with this primitive. Defaults to "".
+"""
+
 Frame2D.add_text = add_text
+Frame2D.add_text.__doc__ = """Add some text to the frame.
+
+Args:
+    self (Frame2D): The self reference
+    text (str): the text to display
+    left (float): the pixel position of the left side of the text
+    bottom (float): the pixel position of the bottom of the text
+    color (np.ndarray, optional): the color of the text. Defaults to White.
+    size_in_pixels (float, optional): the vertical size of the text in pixels. Defaults to 12.0.
+    font_family (str, optional): the font to use for the text. Defaults to "sans-serif".
+    layer_id (str, optional): Unique ID of the layer associated with this primitive. Defaults to "".
+"""

src/scenepic/frame3d.py

@@ -42,5 +42,31 @@ def set_layer_settings(self, layer_settings: Mapping[str, Union[dict, LayerSetti
 
 
 Frame3D.add_meshes = add_meshes
+Frame3D.add_meshes.__doc__ = """Adds meshes to the frame.
+
+Args:
+    meshes (List[Union[Mesh, MeshUpdate, str]]): A list of meshes and mesh updates (or their IDs)
+    transform (np.ndarray, optional): an optional transform to apply to each mesh. Defaults to None.
+"""
+
 Frame3D.add_mesh = add_mesh
+Frame3D.add_mesh.__doc__ = """Adds a mesh to the frame.
+
+Args:
+    mesh (Union[Mesh, MeshUpdate, str]): The mesh, mesh update, or mesh ID
+    transform (np.ndarray, optional): An optional transform to apply to the mesh. Defaults to None.
+"""
+
 Frame3D.set_layer_settings = set_layer_settings
+Frame3D.set_layer_settings.__doc__ = """Specify the visibilities and opacities of certain mesh layers.
+
+Description:
+    Each Mesh object can optionally be part of a user-identified layer
+    (see Mesh constructor).
+    Calling set_layer_settings will result in an additional drop-down
+    selector in the ScenePic user interface.
+
+Args:
+    layer_settings (Mapping[str, Union[dict, LayerSettings]]): a LayerSettings object
+        or a dictionary. See LayerSettings for details.
+"""

src/scenepic/image.py

@@ -31,14 +31,30 @@ def from_numpy(self, array: np.ndarray, format_str="png"):  # noqa: A002
     buff.close()
 
 
-def _data_get(self):
+def _data_get(self) -> bytes:
     return bytes(self.data_get_)
 
 
-def _data_set(self, data):
+def _data_set(self, data: bytes):
     self.data_set_(list(data))
 
 
 Image.load_from_buffer = load_from_buffer
+Image.load_from_buffer.__doc__ = """Load an image from a pre-existing data buffer and extension.
+
+Args:
+    self (Image): self reference
+    data (bytes): the binary data for the image
+    ext (str): the format of the image data [e.g. "gif", "jpg", "png"]
+"""
+
 Image.from_numpy = from_numpy
-Image.data = property(_data_get, _data_set)
+Image.from_numpy.__doc__ = """Loads the image object from raw RGB values provided as a numpy array.
+
+Args:
+    self (Image): self reference
+    array (np.ndarray): The raw pixel RGB as either 0-255 bytes or 0-1 floats.
+    format_str (str, optional): The format to use when compressing the image. Defaults to "png".
+"""
+
+Image.data = property(_data_get, _data_set, doc="""The binary image data.""")

src/scenepic/mesh.py

@@ -49,7 +49,28 @@ def difference_range(self, vertex_buffer: VertexBuffer) -> float:
     self.difference_range_(vertex_buffer._values)
 
 
-Mesh.vertex_buffer = property(vertex_buffer)
-MeshUpdate.vertex_buffer = property(vertex_buffer)
+Mesh.vertex_buffer = property(vertex_buffer, doc="""The raw vertex buffer.""")
+
+MeshUpdate.vertex_buffer = property(vertex_buffer, doc="""The raw vertex buffer.""")
+
 MeshUpdate.quantize = quantize
+MeshUpdate.quantize.__doc__ = """Quantize the mesh update.
+
+Args:
+    self (MeshUpdate): self reference
+    keyframe_index (int): Index of the keyframe to use in quantizing this update
+    fixed_point_range (float): The range to use for the fixed point representation.
+    keyframe_vertex_buffer (VertexBuffer): The keyframe vertex buffer
+"""
+
 MeshUpdate.difference_range = difference_range
+MeshUpdate.difference_range.__doc__ = """Returns the absolute range of values in the difference between this update and the buffer.
+
+Args:
+    self (MeshUpdate): self reference
+    vertex_buffer (VertexBuffer): the buffer to use in the comparison
+
+Return:
+    float: the absolute range (from minimum to maximum) in the per-index difference between
+        this update and the reference.
+"""

src/scenepic/scene.py

@@ -51,6 +51,56 @@ window.Element = element;
 
 
 Scene.link_canvas_events = link_canvas_events
+Scene.link_canvas_events.__doc__ = """Specify that all input events should be linked across the provided set of Canvases.
+
+Args:
+    self (Scene): self reference
+    canvases: the canvases which should have linked events
+"""
+
 Scene.create_mesh = create_mesh
+Scene.create_mesh.__doc__ = """Create a new Mesh and append to the Scene.
+
+Description:
+    Meshes are Scene-wide resources that can be reused across multiple
+    Frames in multiple Canvas3Ds.
+
+Args:
+    mesh_id (str, optional): a unique identifier for the Mesh (will be
+                            automatically populated if not provided). Defaults to None.
+    layer_id (str, optional): an identifier to allow several Meshes to be grouped together
+                            into a "layer".  Layers should be used in conjunction with
+                            Canvas3D.set_layer_settings(). Defaults to None.
+    double_sided (bool, optional): whether to turn off back face culling and draw the Mesh's
+                                triangles as double sided. Defaults to False.
+    camera_space (bool, optional): whether this Mesh is defined in camera space (cannot
+                                be moved in the ScenePic user interface) or world space (standard).
+                                Defaults to False.
+    shared_color (np.ndarray, optional): see `Mesh` constructor.
+    texture_id (Union[Image, str], optional): see `Mesh` constructor.
+    nn_texture (bool, optional): whether the shader should use nearest-neighbor
+                texture interpolation. Defaults to True.
+    use_texture_alpha (bool, optional): whether to use the alpha channel in the texture
+                                        for transparency (only relevant for textured Meshes).
+                                        Defaults to True.
+    is_billboard (bool, optional): draw this Mesh as a billboard (i.e. always facing the user)
+                                rather than rotating with the rest of the world. Defaults to False.
+    is_label (bool, optional): this mesh will be treated specially as a label. Not for public use.
+                            Defaults to False.
+
+Returns:
+    Mesh: a reference to the new Mesh object
+"""
+
+
 Scene.simulate_key_presses = simulate_key_presses
+Scene.simulate_key_presses.__doc__ = """Simulates one or more keypresses to fire off events in the ScenePic UI at startup, e.g. video playback.
+
+Args:
+    self (Scene): self reference
+    canvas_id (Union[Canvas3D, Canvas2D, str]): ID of the canvas on which to fire off this
+                                                event.
+    keypresses: the key values
+"""
+
 Scene._repr_javascript_ = _repr_javascript_

src/scenepic/version.py

@@ -3,4 +3,4 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 
-__version__ = "1.0.14"
+__version__ = "1.0.15"

src/scenepic/video.py

@@ -11,13 +11,20 @@ def load_from_buffer(self, data: bytes, ext: str):
     self.ext = ext
 
 
-def _data_get(self):
+def _data_get(self) -> bytes:
     return bytes(self.data_get_)
 
 
-def _data_set(self, data):
+def _data_set(self, data: bytes):
     self.data_set_(list(data))
 
 
 Video.load_from_buffer = load_from_buffer
-Video.data = property(_data_get, _data_set)
+Video.load_from_buffer.__doc__ = """Load video from a pre-existing data buffer and extension.
+
+Args:
+    data (bytes): the binary data for the video
+    ext (str): the file extension (e.g. mp4, mkv)
+"""
+
+Video.data = property(_data_get, _data_set, doc="""The binary video data.""")