More renderer parameter descriptions

Summary:
Copy some descriptions of renderer parameters to more places so they are easier to find.

Also a couple of small corrections, and make RasterizationSettings a dataclass.

Reviewed By: nikhilaravi, patricklabatut

Differential Revision: D30899822

fbshipit-source-id: 805cf366acb7d51cb308fa574deff0657c199673

pytorch3d/renderer/blending.py

@@ -16,8 +16,22 @@ from pytorch3d import _C
 # NOTE: All blending function should return an RGBA image per batch element
 
 
-# Data class to store blending params with defaults
 class BlendParams(NamedTuple):
+    """
+    Data class to store blending params with defaults
+
+    Members:
+        sigma (float): Controls the width of the sigmoid function used to
+            calculate the 2D distance based probability. Determines the
+            sharpness of the edges of the shape.
+            Higher => faces have less defined edges.
+        gamma (float): Controls the scaling of the exponential function used
+            to set the opacity of the color.
+            Higher => faces are more transparent.
+        background_color: RGB values for the background color as a tuple or
+            as a tensor of three floats.
+    """
+
     sigma: float = 1e-4
     gamma: float = 1e-4
     background_color: Union[torch.Tensor, Sequence[float]] = (1.0, 1.0, 1.0)

pytorch3d/renderer/mesh/rasterize_meshes.py

@@ -73,12 +73,15 @@ def rasterize_meshes(
             affect the output, but can affect the speed of the forward pass.
         faces_per_bin: Only applicable when using coarse-to-fine rasterization
             (bin_size > 0); this is the maximum number of faces allowed within each
-            bin. If more than this many faces actually fall into a bin, an error
+            bin. This should not affect the output values, but can affect
-            will be raised. This should not affect the output values, but can affect
             the memory usage in the forward pass.
         perspective_correct: Bool, Whether to apply perspective correction when computing
             barycentric coordinates for pixels. This should be set to True if a perspective
             camera is used.
+        clip_barycentric_coords: Whether, after any perspective correction is applied
+            but before the depth is calculated (e.g. for z clipping),
+            to "correct" a location outside the face (i.e. with a negative
+            barycentric coordinate) to a position on the edge of the face.
         cull_backfaces: Bool, Whether to only rasterize mesh faces which are
             visible to the camera.  This assumes that vertices of
             front-facing triangles are ordered in an anti-clockwise

pytorch3d/renderer/mesh/rasterizer.py

@@ -4,6 +4,7 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
+from dataclasses import dataclass
 from typing import NamedTuple, Optional, Tuple, Union
 
 import torch
@@ -20,46 +21,66 @@ class Fragments(NamedTuple):
     dists: torch.Tensor
 
 
-# Class to store the mesh rasterization params with defaults
+@dataclass
 class RasterizationSettings:
-    __slots__ = [
+    """
-        "image_size",
+    Class to store the mesh rasterization params with defaults
-        "blur_radius",
-        "faces_per_pixel",
-        "bin_size",
-        "max_faces_per_bin",
-        "perspective_correct",
-        "clip_barycentric_coords",
-        "cull_backfaces",
-        "z_clip_value",
-        "cull_to_frustum",
-    ]
 
-    def __init__(
+    Members:
-        self,
+        image_size: Either common height and width or (height, width), in pixels.
-        image_size: Union[int, Tuple[int, int]] = 256,
+        blur_radius: Float distance in the range [0, 2] used to expand the face
-        blur_radius: float = 0.0,
+            bounding boxes for rasterization. Setting blur radius
-        faces_per_pixel: int = 1,
+            results in blurred edges around the shape instead of a
-        bin_size: Optional[int] = None,
+            hard boundary. Set to 0 for no blur.
-        max_faces_per_bin: Optional[int] = None,
+        faces_per_pixel: (int) Number of faces to keep track of per pixel.
-        # set perspective_correct = None so that the
+            We return the nearest faces_per_pixel faces along the z-axis.
-        # value can be inferred correctly from the Camera type
+        bin_size: Size of bins to use for coarse-to-fine rasterization. Setting
-        perspective_correct: Optional[bool] = None,
+            bin_size=0 uses naive rasterization; setting bin_size=None attempts
-        clip_barycentric_coords: Optional[bool] = None,
+            to set it heuristically based on the shape of the input. This should
-        cull_backfaces: bool = False,
+            not affect the output, but can affect the speed of the forward pass.
-        z_clip_value: Optional[float] = None,
+        max_faces_per_bin: Only applicable when using coarse-to-fine
-        cull_to_frustum: bool = False,
+            rasterization (bin_size != 0); this is the maximum number of faces
-    ) -> None:
+            allowed within each bin. This should not affect the output values,
-        self.image_size = image_size
+            but can affect the memory usage in the forward pass.
-        self.blur_radius = blur_radius
+            Setting max_faces_per_bin=None attempts to set with a heuristic.
-        self.faces_per_pixel = faces_per_pixel
+        perspective_correct: Whether to apply perspective correction when
-        self.bin_size = bin_size
+            computing barycentric coordinates for pixels.
-        self.max_faces_per_bin = max_faces_per_bin
+            None (default) means make correction if the camera uses perspective.
-        self.perspective_correct = perspective_correct
+        clip_barycentric_coords: Whether, after any perspective correction
-        self.clip_barycentric_coords = clip_barycentric_coords
+            is applied but before the depth is calculated (e.g. for
-        self.cull_backfaces = cull_backfaces
+            z clipping), to "correct" a location outside the face (i.e. with
-        self.z_clip_value = z_clip_value
+            a negative barycentric coordinate) to a position on the edge of the
-        self.cull_to_frustum = cull_to_frustum
+            face. None (default) means clip if blur_radius > 0, which is a condition
+            under which such outside-face-points are likely.
+        cull_backfaces: Whether to only rasterize mesh faces which are
+            visible to the camera.  This assumes that vertices of
+            front-facing triangles are ordered in an anti-clockwise
+            fashion, and triangles that face away from the camera are
+            in a clockwise order relative to the current view
+            direction. NOTE: This will only work if the mesh faces are
+            consistently defined with counter-clockwise ordering when
+            viewed from the outside.
+        z_clip_value: if not None, then triangles will be clipped (and possibly
+            subdivided into smaller triangles) such that z >= z_clip_value.
+            This avoids camera projections that go to infinity as z->0.
+            Default is None as clipping affects rasterization speed and
+            should only be turned on if explicitly needed.
+            See clip.py for all the extra computation that is required.
+        cull_to_frustum: Whether to cull triangles outside the view frustum.
+            Culling involves removing all faces which fall outside view frustum.
+            Default is False for performance as often not needed.
+    """
+
+    image_size: Union[int, Tuple[int, int]] = 256
+    blur_radius: float = 0.0
+    faces_per_pixel: int = 1
+    bin_size: Optional[int] = None
+    max_faces_per_bin: Optional[int] = None
+    perspective_correct: Optional[bool] = None
+    clip_barycentric_coords: Optional[bool] = None
+    cull_backfaces: bool = False
+    z_clip_value: Optional[float] = None
+    cull_to_frustum: bool = False
 
 
 class MeshRasterizer(nn.Module):

pytorch3d/renderer/points/rasterize_points.py

@@ -64,8 +64,7 @@ def rasterize_points(
             affect the output, but can affect the speed of the forward pass.
         points_per_bin: Only applicable when using coarse-to-fine rasterization
             (bin_size > 0); this is the maximum number of points allowed within each
-            bin. If more than this many points actually fall into a bin, an error
+            bin. This should not affect the output values, but can affect
-            will be raised. This should not affect the output values, but can affect
             the memory usage in the forward pass.
 
     Returns:

pytorch3d/renderer/points/rasterizer.py

@@ -5,7 +5,7 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
-
+from dataclasses import dataclass
 from typing import NamedTuple, Optional, Tuple, Union
 
 import torch
@@ -21,29 +21,35 @@ class PointFragments(NamedTuple):
     dists: torch.Tensor
 
 
-# Class to store the point rasterization params with defaults
+@dataclass
 class PointsRasterizationSettings:
-    __slots__ = [
+    """
-        "image_size",
+    Class to store the point rasterization params with defaults
-        "radius",
-        "points_per_pixel",
-        "bin_size",
-        "max_points_per_bin",
-    ]
 
-    def __init__(
+    Members:
-        self,
+        image_size: Either common height and width or (height, width), in pixels.
-        image_size: Union[int, Tuple[int, int]] = 256,
+        radius: The radius (in NDC units) of each disk to be rasterized.
-        radius: Union[float, torch.Tensor] = 0.01,
+            This can either be a float in which case the same radius is used
-        points_per_pixel: int = 8,
+            for each point, or a torch.Tensor of shape (N, P) giving a radius
-        bin_size: Optional[int] = None,
+            per point in the batch.
-        max_points_per_bin: Optional[int] = None,
+        points_per_pixel: (int) Number of points to keep track of per pixel.
-    ) -> None:
+            We return the nearest points_per_pixel points along the z-axis.
-        self.image_size = image_size
+        bin_size: Size of bins to use for coarse-to-fine rasterization. Setting
-        self.radius = radius
+            bin_size=0 uses naive rasterization; setting bin_size=None attempts
-        self.points_per_pixel = points_per_pixel
+            to set it heuristically based on the shape of the input. This should
-        self.bin_size = bin_size
+            not affect the output, but can affect the speed of the forward pass.
-        self.max_points_per_bin = max_points_per_bin
+        max_points_per_bin: Only applicable when using coarse-to-fine
+            rasterization (bin_size != 0); this is the maximum number of points
+            allowed within each bin. This should not affect the output values,
+            but can affect the memory usage in the forward pass.
+            Setting max_points_per_bin=None attempts to set with a heuristic.
+    """
+
+    image_size: Union[int, Tuple[int, int]] = 256
+    radius: Union[float, torch.Tensor] = 0.01
+    points_per_pixel: int = 8
+    bin_size: Optional[int] = None
+    max_points_per_bin: Optional[int] = None
 
 
 class PointsRasterizer(nn.Module):

pytorch3d/transforms/math.py

@@ -5,10 +5,11 @@
 # LICENSE file in the root directory of this source tree.
 
 import math
-from typing import Tuple, Union
+from typing import Tuple
 
 import torch
 
+
 DEFAULT_ACOS_BOUND = 1.0 - 1e-4
 
 
@@ -27,9 +28,11 @@ def acos_linear_extrapolation(
     if lower_bound <= x <= upper_bound:
         acos_linear_extrapolation(x) = acos(x)
     elif x <= lower_bound: # 1st order Taylor approximation
-        acos_linear_extrapolation(x) = acos(lower_bound) + dacos/dx(lower_bound) * (x - lower_bound)
+        acos_linear_extrapolation(x)
+            = acos(lower_bound) + dacos/dx(lower_bound) * (x - lower_bound)
     else:  # x >= upper_bound
-        acos_linear_extrapolation(x) = acos(upper_bound) + dacos/dx(upper_bound) * (x - upper_bound)
+        acos_linear_extrapolation(x)
+            = acos(upper_bound) + dacos/dx(upper_bound) * (x - upper_bound)
     ```
 
     Args: