diff --git a/pytorch3d/renderer/blending.py b/pytorch3d/renderer/blending.py index 8bc26ea0..22401b81 100644 --- a/pytorch3d/renderer/blending.py +++ b/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) diff --git a/pytorch3d/renderer/mesh/rasterize_meshes.py b/pytorch3d/renderer/mesh/rasterize_meshes.py index e9d7fd89..e10ff92b 100644 --- a/pytorch3d/renderer/mesh/rasterize_meshes.py +++ b/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 - will be raised. This should not affect the output values, but can affect + bin. 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 diff --git a/pytorch3d/renderer/mesh/rasterizer.py b/pytorch3d/renderer/mesh/rasterizer.py index 9e49124a..59a061b2 100644 --- a/pytorch3d/renderer/mesh/rasterizer.py +++ b/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", - "blur_radius", - "faces_per_pixel", - "bin_size", - "max_faces_per_bin", - "perspective_correct", - "clip_barycentric_coords", - "cull_backfaces", - "z_clip_value", - "cull_to_frustum", - ] + """ + Class to store the mesh rasterization params with defaults - def __init__( - self, - 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, - # set perspective_correct = None so that the - # value can be inferred correctly from the Camera type - 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, - ) -> None: - self.image_size = image_size - self.blur_radius = blur_radius - self.faces_per_pixel = faces_per_pixel - self.bin_size = bin_size - self.max_faces_per_bin = max_faces_per_bin - self.perspective_correct = perspective_correct - self.clip_barycentric_coords = clip_barycentric_coords - self.cull_backfaces = cull_backfaces - self.z_clip_value = z_clip_value - self.cull_to_frustum = cull_to_frustum + Members: + image_size: Either common height and width or (height, width), in pixels. + blur_radius: Float distance in the range [0, 2] used to expand the face + bounding boxes for rasterization. Setting blur radius + results in blurred edges around the shape instead of a + hard boundary. Set to 0 for no blur. + faces_per_pixel: (int) Number of faces to keep track of per pixel. + We return the nearest faces_per_pixel faces along the z-axis. + bin_size: Size of bins to use for coarse-to-fine rasterization. Setting + bin_size=0 uses naive rasterization; setting bin_size=None attempts + to set it heuristically based on the shape of the input. This should + not affect the output, but can affect the speed of the forward pass. + max_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. This should not affect the output values, + but can affect the memory usage in the forward pass. + Setting max_faces_per_bin=None attempts to set with a heuristic. + perspective_correct: Whether to apply perspective correction when + computing barycentric coordinates for pixels. + None (default) means make correction if the camera uses perspective. + 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. 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): diff --git a/pytorch3d/renderer/points/rasterize_points.py b/pytorch3d/renderer/points/rasterize_points.py index 443c83cd..d2741760 100644 --- a/pytorch3d/renderer/points/rasterize_points.py +++ b/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 - will be raised. This should not affect the output values, but can affect + bin. This should not affect the output values, but can affect the memory usage in the forward pass. Returns: diff --git a/pytorch3d/renderer/points/rasterizer.py b/pytorch3d/renderer/points/rasterizer.py index fe3dfd51..f9ab7993 100644 --- a/pytorch3d/renderer/points/rasterizer.py +++ b/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", - "radius", - "points_per_pixel", - "bin_size", - "max_points_per_bin", - ] + """ + Class to store the point rasterization params with defaults - def __init__( - self, - 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, - ) -> None: - self.image_size = image_size - self.radius = radius - self.points_per_pixel = points_per_pixel - self.bin_size = bin_size - self.max_points_per_bin = max_points_per_bin + Members: + image_size: Either common height and width or (height, width), in pixels. + radius: The radius (in NDC units) of each disk to be rasterized. + This can either be a float in which case the same radius is used + for each point, or a torch.Tensor of shape (N, P) giving a radius + per point in the batch. + points_per_pixel: (int) Number of points to keep track of per pixel. + We return the nearest points_per_pixel points along the z-axis. + bin_size: Size of bins to use for coarse-to-fine rasterization. Setting + bin_size=0 uses naive rasterization; setting bin_size=None attempts + to set it heuristically based on the shape of the input. This should + not affect the output, but can affect the speed of the forward pass. + 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): diff --git a/pytorch3d/transforms/math.py b/pytorch3d/transforms/math.py index 88e3084a..5110cf1d 100644 --- a/pytorch3d/transforms/math.py +++ b/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: