| |
| from typing import List, Tuple, Dict, Union, Optional, Any, overload, Literal, Callable |
| from typing_extensions import Unpack |
| import numpy as numpy_ |
| import torch as torch_ |
| import nvdiffrast.torch |
| import numbers |
| from . import numpy, torch |
| import utils3d.numpy, utils3d.torch |
|
|
| __all__ = ["sliding_window", |
| "pooling", |
| "max_pool_2d", |
| "lookup", |
| "lookup_get", |
| "lookup_set", |
| "group", |
| "csr_matrix_from_dense_indices", |
| "reverse_permutation", |
| "vector_outer", |
| "perspective_from_fov", |
| "perspective_from_window", |
| "intrinsics_from_fov", |
| "intrinsics_from_focal_center", |
| "fov_to_focal", |
| "focal_to_fov", |
| "intrinsics_to_fov", |
| "view_look_at", |
| "extrinsics_look_at", |
| "perspective_to_intrinsics", |
| "perspective_to_near_far", |
| "intrinsics_to_perspective", |
| "extrinsics_to_view", |
| "view_to_extrinsics", |
| "normalize_intrinsics", |
| "denormalize_intrinsics", |
| "crop_intrinsics", |
| "pixel_to_uv", |
| "pixel_to_ndc", |
| "uv_to_pixel", |
| "depth_linear_to_buffer", |
| "depth_buffer_to_linear", |
| "unproject_cv", |
| "unproject_gl", |
| "project_cv", |
| "project_gl", |
| "project", |
| "unproject", |
| "screen_coord_to_view_coord", |
| "quaternion_to_matrix", |
| "quaternion_multiply", |
| "quaternion_inverse", |
| "quaternion_normalize", |
| "axis_angle_to_matrix", |
| "matrix_to_quaternion", |
| "extrinsics_to_essential", |
| "axis_angle_to_quaternion", |
| "euler_axis_angle_rotation", |
| "euler_angles_to_matrix", |
| "matrix_to_axis_angle", |
| "matrix_to_euler_angles", |
| "quaternion_to_axis_angle", |
| "skew_symmetric", |
| "rotation_matrix_from_vectors", |
| "ray_intersection", |
| "make_affine_matrix", |
| "random_rotation_matrix", |
| "lerp", |
| "slerp", |
| "slerp_rotation_matrix", |
| "interpolate_se3_matrix", |
| "piecewise_lerp", |
| "piecewise_interpolate_se3_matrix", |
| "transform_points", |
| "angle_between", |
| "kabasch", |
| "umeyama", |
| "affine_umeyama", |
| "solve_pose", |
| "segment_solve_pose", |
| "solve_poses_sequential", |
| "segment_solve_poses_sequential", |
| "segment_roll", |
| "segment_take", |
| "segment_argmax", |
| "segment_argmin", |
| "segment_concatenate", |
| "segment_concat", |
| "segment_chain", |
| "group_as_segments", |
| "triangulate_mesh", |
| "compute_face_corner_angles", |
| "compute_face_corner_normals", |
| "compute_face_corner_tangents", |
| "compute_face_normals", |
| "compute_face_tangents", |
| "compute_vertex_normals", |
| "remove_corrupted_faces", |
| "merge_duplicate_vertices", |
| "remove_unused_vertices", |
| "subdivide_mesh", |
| "mesh_edges", |
| "mesh_half_edges", |
| "mesh_connected_components", |
| "graph_connected_components", |
| "mesh_adjacency_graph", |
| "flatten_mesh_indices", |
| "create_cube_mesh", |
| "create_icosahedron_mesh", |
| "create_square_mesh", |
| "create_camera_frustum_mesh", |
| "merge_meshes", |
| "uv_map", |
| "pixel_coord_map", |
| "screen_coord_map", |
| "build_grid_mesh", |
| "build_mesh_from_map", |
| "build_mesh_from_depth_map", |
| "depth_map_edge", |
| "depth_map_aliasing", |
| "normal_map_edge", |
| "point_map_to_normal_map", |
| "depth_map_to_point_map", |
| "depth_map_to_normal_map", |
| "chessboard", |
| "masked_nearest_resize", |
| "masked_area_resize", |
| "colorize_depth_map", |
| "colorize_normal_map", |
| "colorize_segmentation_map", |
| "colorize_probability_map", |
| "flood_fill", |
| "perlin_noise", |
| "perlin_noise_map", |
| "fractal_perlin_noise_map", |
| "RastContext", |
| "rasterize_triangles", |
| "rasterize_triangles_peeling", |
| "rasterize_lines", |
| "rasterize_point_cloud", |
| "sample_texture", |
| "test_rasterization", |
| "read_extrinsics_from_colmap", |
| "read_intrinsics_from_colmap", |
| "write_extrinsics_as_colmap", |
| "write_intrinsics_as_colmap", |
| "read_obj", |
| "write_obj", |
| "read_ply", |
| "write_ply", |
| "masked_min", |
| "masked_max", |
| "csr_eliminate_zeros", |
| "lexsort", |
| "index_reduce", |
| "index_reduce_", |
| "scatter_argmax", |
| "scatter_argmin", |
| "large_multinomial", |
| "matrix_trace", |
| "rotation_matrix_2d", |
| "rotate_2d", |
| "translate_2d", |
| "scale_2d", |
| "pose_graph_optimization", |
| "segment_median", |
| "segment_sum", |
| "segment_cumsum", |
| "segment_sort", |
| "segment_argsort", |
| "segment_topk", |
| "stack_segments", |
| "segment_multinomial", |
| "segment_combinations", |
| "segment_searchsorted", |
| "mesh_dual_graph", |
| "compute_boundaries", |
| "remove_isolated_pieces", |
| "compute_mesh_laplacian", |
| "laplacian_smooth_mesh", |
| "taubin_smooth_mesh", |
| "laplacian_hc_smooth_mesh", |
| "bounding_rect_from_mask", |
| "texture_composite"] |
|
|
| @overload |
| def sliding_window(x: numpy_.ndarray, window_size: Union[int, Tuple[int, ...]], stride: Union[int, Tuple[int, ...], NoneType] = None, dilation: Union[int, Tuple[int, ...], NoneType] = None, pad_size: Union[int, Tuple[int, int], Tuple[Tuple[int, int]], NoneType] = None, pad_mode: str = 'constant', pad_value: numbers.Number = 0, axis: Optional[Tuple[int, ...]] = None) -> numpy_.ndarray: |
| """Get a sliding window of the input array. Window axis(axes) will be appended as the last dimension(s). |
| This function is a wrapper of `numpy.lib.stride_tricks.sliding_window_view` with additional support for padding and stride. |
| |
| ## Parameters |
| - `x` (ndarray): Input array. |
| - `window_size` (int or Tuple[int,...]): Size of the sliding window. If int |
| is provided, the same size is used for all specified axes. |
| - `stride` (Optional[Tuple[int,...]]): Stride between the sliding windows. If None, |
| no stride is applied. If int is provided, the same stride is used for all specified axes. |
| - `dilation` (Optional[Tuple[int,...]]): Dilation in each sliding window. If None, |
| no dilation is applied. If int is provided, the same dilation is used for all specified axes. |
| - `pad_size` (Optional[Union[int, Tuple[int, int], Tuple[Tuple[int, int]]]]): Size of padding to apply before sliding window. |
| Corresponding to `axis`. |
| - General format is `((before_1, after_1), (before_2, after_2), ...)`. |
| - Shortcut formats: |
| - `int` -> same padding before and after for all axes; |
| - `(int, int)` -> same padding before and after for each axis; |
| - `((int,), (int,) ...)` -> specify padding for each axis, same before and after. |
| - `pad_mode` (str): Padding mode to use. Refer to `numpy.pad` for more details. |
| - `pad_value` (Union[int, float]): Value to use for constant padding. Only used |
| when `pad_mode` is 'constant'. |
| - `axis` (Optional[Tuple[int,...]]): Axes to apply the sliding window. If None, all axes are used. |
| |
| ## Returns |
| - (ndarray): Sliding window of the input array. |
| - If no padding, the output is a view of the input array with zero copy. |
| - Otherwise, the output is no longer a view but a copy of the padded array.""" |
| utils3d.numpy.utils.sliding_window |
|
|
| @overload |
| def pooling(x: numpy_.ndarray, kernel_size: Union[int, Tuple[int, ...]], stride: Union[int, Tuple[int, ...], NoneType] = None, padding: Union[int, Tuple[int, int], Tuple[Tuple[int, int]], NoneType] = None, axis: Union[int, Tuple[int, ...], NoneType] = None, mode: Literal['min', 'max', 'sum', 'mean'] = 'max') -> numpy_.ndarray: |
| """Compute the pooling of the input array. |
| NOTE: NaNs will be ignored. |
| |
| ## Parameters |
| - `x` (ndarray): Input array. |
| - `kernel_size` (int or Tuple[int,...]): Size of the pooling window. |
| - `stride` (Optional[Tuple[int,...]]): Stride of the pooling window. If None, |
| no stride is applied. If int is provided, the same stride is used for all specified axes. |
| - `padding` (Optional[Union[int, Tuple[int, int], Tuple[Tuple[int, int]]]]): Size of padding to apply before pooling. |
| Corresponding to `axis`. |
| - General format is `((before_1, after_1), (before_2, after_2), ...)`. |
| - Shortcut formats: |
| - `int` -> same padding before and after for all axes; |
| - `(int, int)` -> same padding before and after for each axis; |
| - `((int,), (int,) ...)` -> specify padding for each axis, same before and after. |
| - `axis` (Optional[Tuple[int,...]]): Axes to apply the pooling. If None, all axes are used. |
| - `mode` (str): Pooling mode. One of 'min', 'max', 'sum', 'mean'. |
| |
| ## Returns |
| - (ndarray): Pooled array with the same number of dimensions as input array.""" |
| utils3d.numpy.utils.pooling |
|
|
| @overload |
| def max_pool_2d(x: numpy_.ndarray, kernel_size: Union[int, Tuple[int, int]], stride: Union[int, Tuple[int, int]], padding: Union[int, Tuple[int, int]], axis: Tuple[int, int] = (-2, -1)): |
| utils3d.numpy.utils.max_pool_2d |
|
|
| @overload |
| def lookup(key: numpy_.ndarray, query: numpy_.ndarray) -> numpy_.ndarray: |
| """Look up `query` in `key` like a dictionary. Useful for COO indexing. |
| |
| Parameters |
| ---- |
| - `key` (ndarray): shape `(num_keys, *key_shape)`, the array to search in |
| - `query` (ndarray): shape `(..., *key_shape)`, the array to search for. `...` represents any number of batch dimensions. |
| |
| Returns |
| ---- |
| - `indices` (ndarray): shape `(...,)` indices in `key` for each `query`. If a query is not found in key, the corresponding index will be -1. |
| |
| Notes |
| ---- |
| `O((Q + K) * log(Q + K))` complexity, where `Q` is the number of queries and `K` is the number of keys.""" |
| utils3d.numpy.utils.lookup |
|
|
| @overload |
| def lookup_get(key: numpy_.ndarray, value: numpy_.ndarray, get_key: numpy_.ndarray, default_value: Union[numbers.Number, numpy_.ndarray] = 0) -> numpy_.ndarray: |
| """Dictionary-like get for arrays |
| |
| ## Parameters |
| - `key` (ndarray): shape `(N, *key_shape)`, the key array of the dictionary to get from |
| - `value` (ndarray): shape `(N, *value_shape)`, the value array of the dictionary to get from |
| - `get_key` (ndarray): shape `(..., *key_shape)`, the key array to get for. `...` represents any number of batch dimensions. |
| - `default_value` (Union[Number, ndarray]): a scalar or an array broadcastable to shape `(..., *value_shape)`. Value to return if a key in `get_key` is not found in `key`. |
| |
| ## Returns |
| `get_value` (ndarray): shape `(..., *value_shape)`, result values corresponding to `get_key`""" |
| utils3d.numpy.utils.lookup_get |
|
|
| @overload |
| def lookup_set(key: numpy_.ndarray, value: numpy_.ndarray, set_key: numpy_.ndarray, set_value: numpy_.ndarray, append: bool = False, inplace: bool = False) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Dictionary-like set for arrays. |
| |
| ## Parameters |
| - `key` (ndarray): shape `(N, *key_shape)`, the key array of the dictionary to set |
| - `value` (ndarray): shape `(N, *value_shape)`, the value array of the dictionary to set |
| - `set_key` (ndarray): shape `(M, *key_shape)`, the key array to set for |
| - `set_value` (ndarray): shape `(M, *value_shape)`, the value array to set as |
| - `append` (bool): If True, append the (key, value) pairs in (set_key, set_value) that are not in (key, value) to the result. |
| - `inplace` (bool): If True, modify the input `value` array |
| |
| ## Returns |
| - `result_key` (ndarray): shape `(N_new, *value_shape)`. N_new = N + number of new keys added if append is True, else N. |
| - `result_value (ndarray): shape `(N_new, *value_shape)` """ |
| utils3d.numpy.utils.lookup_set |
|
|
| @overload |
| def group(labels: numpy_.ndarray, data: Optional[numpy_.ndarray] = None) -> List[Tuple[numpy_.ndarray, numpy_.ndarray]]: |
| """Split the data into groups based on the provided labels. |
| |
| ## Parameters |
| - `labels` `(ndarray)` shape `(N, *label_dims)` array of labels for each data point. Labels can be multi-dimensional. |
| - `data`: `(ndarray, optional)` shape `(N, *data_dims)` dense tensor. Each one in `N` has `D` features. |
| If None, return the indices in each group instead. |
| |
| ## Returns |
| - `groups` `(List[Tuple[ndarray, ndarray]])`: List of each group, a tuple of `(label, data_in_group)`. |
| - `label` (ndarray): shape `(*label_dims,)` the label of the group. |
| - `data_in_group` (ndarray): shape `(length_of_group, *data_dims)` the data points in the group. |
| If `data` is None, `data_in_group` will be the indices of the data points in the original array.""" |
| utils3d.numpy.utils.group |
|
|
| @overload |
| def csr_matrix_from_dense_indices(indices: numpy_.ndarray, n_cols: int) -> 'csr_array': |
| """Convert a regular indices array to a sparse CSR adjacency matrix format |
| |
| ## Parameters |
| - `indices` (ndarray): shape (N, M) dense tensor. Each one in `N` has `M` connections. |
| - `n_cols` (int): total number of columns in the adjacency matrix |
| |
| ## Returns |
| Tensor: shape `(N, n_cols)` sparse CSR adjacency matrix""" |
| utils3d.numpy.utils.csr_matrix_from_dense_indices |
|
|
| @overload |
| def reverse_permutation(perm: numpy_.ndarray, axis: int = 0) -> numpy_.ndarray: |
| """Compute the reverse of a permutation array. |
| |
| Parameters |
| ---- |
| - `perm` (ndarray): shape `(..., N, ...)` permutation array. |
| - `axis` (int): axis of the permutation array. Other axes are treated as batch dimensions. |
| |
| Returns |
| ---- |
| - `rev_perm` (ndarray): shape `(N,)` reverse permutation array. |
| |
| Notes |
| ----- |
| Equivalent to `np.argsort(perm, axis=axis)`, but more efficient.""" |
| utils3d.numpy.utils.reverse_permutation |
|
|
| @overload |
| def vector_outer(x: numpy_.ndarray, y: Optional[numpy_.ndarray] = None) -> numpy_.ndarray: |
| """Compute the outer product of two arrays. |
| |
| Parameters |
| ---- |
| - `x` (ndarray): shape `(..., M)` first array. |
| - `y` (ndarray, optional): shape `(..., N)` second array. If None, compute the outer product of `x` with itself. |
| |
| Returns |
| ---- |
| - `outer` (ndarray): shape `(..., M, N)` outer product of `x` and `y`.""" |
| utils3d.numpy.utils.vector_outer |
|
|
| @overload |
| def perspective_from_fov(*, fov_x: Union[float, numpy_.ndarray, NoneType] = None, fov_y: Union[float, numpy_.ndarray, NoneType] = None, fov_min: Union[float, numpy_.ndarray, NoneType] = None, fov_max: Union[float, numpy_.ndarray, NoneType] = None, aspect_ratio: Union[float, numpy_.ndarray, NoneType] = None, near: Union[float, numpy_.ndarray, NoneType], far: Union[float, numpy_.ndarray, NoneType]) -> numpy_.ndarray: |
| """Get OpenGL perspective matrix from field of view |
| |
| ## Returns |
| (ndarray): [..., 4, 4] perspective matrix""" |
| utils3d.numpy.transforms.perspective_from_fov |
|
|
| @overload |
| def perspective_from_window(left: Union[float, numpy_.ndarray], right: Union[float, numpy_.ndarray], bottom: Union[float, numpy_.ndarray], top: Union[float, numpy_.ndarray], near: Union[float, numpy_.ndarray], far: Union[float, numpy_.ndarray]) -> numpy_.ndarray: |
| """Get OpenGL perspective matrix from the window of z=-1 projection plane |
| |
| ## Returns |
| (ndarray): [..., 4, 4] perspective matrix""" |
| utils3d.numpy.transforms.perspective_from_window |
|
|
| @overload |
| def intrinsics_from_fov(*, fov_x: Union[float, numpy_.ndarray, NoneType] = None, fov_y: Union[float, numpy_.ndarray, NoneType] = None, fov_max: Union[float, numpy_.ndarray, NoneType] = None, fov_min: Union[float, numpy_.ndarray, NoneType] = None, cx: Union[float, numpy_.ndarray] = 0.5, cy: Union[float, numpy_.ndarray] = 0.5, aspect_ratio: Union[float, numpy_.ndarray, NoneType] = None) -> numpy_.ndarray: |
| """Get normalized OpenCV intrinsics matrix from given field of view. |
| You can provide either fov_x, fov_y, fov_max or fov_min and aspect_ratio |
| |
| Parameters |
| ---- |
| fov_x (float | ndarray): field of view in x axis |
| fov_y (float | ndarray): field of view in y axis |
| fov_max (float | ndarray): field of view in largest dimension |
| fov_min (float | ndarray): field of view in smallest dimension |
| cx (float | ndarray): principal point x coordinate |
| cy (float | ndarray): principal point y coordinate |
| aspect_ratio (float | ndarray): aspect ratio of the image |
| |
| Returns |
| ---- |
| (ndarray): [..., 3, 3] OpenCV intrinsics matrix""" |
| utils3d.numpy.transforms.intrinsics_from_fov |
|
|
| @overload |
| def intrinsics_from_focal_center(fx: Union[float, numpy_.ndarray], fy: Union[float, numpy_.ndarray], cx: Union[float, numpy_.ndarray], cy: Union[float, numpy_.ndarray]) -> numpy_.ndarray: |
| """Get OpenCV intrinsics matrix |
| |
| ## Returns |
| (ndarray): [..., 3, 3] OpenCV intrinsics matrix""" |
| utils3d.numpy.transforms.intrinsics_from_focal_center |
|
|
| @overload |
| def fov_to_focal(fov: numpy_.ndarray): |
| utils3d.numpy.transforms.fov_to_focal |
|
|
| @overload |
| def focal_to_fov(focal: numpy_.ndarray): |
| utils3d.numpy.transforms.focal_to_fov |
|
|
| @overload |
| def intrinsics_to_fov(intrinsics: numpy_.ndarray) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| utils3d.numpy.transforms.intrinsics_to_fov |
|
|
| @overload |
| def view_look_at(eye: numpy_.ndarray, look_at: numpy_.ndarray, up: numpy_.ndarray) -> numpy_.ndarray: |
| """Get OpenGL view matrix looking at something |
| |
| ## Parameters |
| eye (ndarray): [..., 3] the eye position |
| look_at (ndarray): [..., 3] the position to look at |
| up (ndarray): [..., 3] head up direction (y axis in screen space). Not necessarily othogonal to view direction |
| |
| ## Returns |
| (ndarray): [..., 4, 4], view matrix""" |
| utils3d.numpy.transforms.view_look_at |
|
|
| @overload |
| def extrinsics_look_at(eye: numpy_.ndarray, look_at: numpy_.ndarray, up: numpy_.ndarray) -> numpy_.ndarray: |
| """Get OpenCV extrinsics matrix looking at something |
| |
| ## Parameters |
| eye (ndarray): [..., 3] the eye position |
| look_at (ndarray): [..., 3] the position to look at |
| up (ndarray): [..., 3] head up direction (-y axis in screen space). Not necessarily othogonal to view direction |
| |
| ## Returns |
| (ndarray): [..., 4, 4], extrinsics matrix""" |
| utils3d.numpy.transforms.extrinsics_look_at |
|
|
| @overload |
| def perspective_to_intrinsics(perspective: numpy_.ndarray) -> numpy_.ndarray: |
| """OpenGL perspective matrix to OpenCV intrinsics |
| |
| ## Parameters |
| perspective (ndarray): [..., 4, 4] OpenGL perspective matrix |
| |
| ## Returns |
| (ndarray): shape [..., 3, 3] OpenCV intrinsics""" |
| utils3d.numpy.transforms.perspective_to_intrinsics |
|
|
| @overload |
| def perspective_to_near_far(perspective: numpy_.ndarray) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Get near and far planes from OpenGL perspective matrix |
| |
| ## Parameters""" |
| utils3d.numpy.transforms.perspective_to_near_far |
|
|
| @overload |
| def intrinsics_to_perspective(intrinsics: numpy_.ndarray, near: Union[float, numpy_.ndarray], far: Union[float, numpy_.ndarray]) -> numpy_.ndarray: |
| """OpenCV intrinsics to OpenGL perspective matrix |
| |
| ## Parameters |
| intrinsics (ndarray): [..., 3, 3] OpenCV intrinsics matrix |
| near (float | ndarray): [...] near plane to clip |
| far (float | ndarray): [...] far plane to clip |
| ## Returns |
| (ndarray): [..., 4, 4] OpenGL perspective matrix""" |
| utils3d.numpy.transforms.intrinsics_to_perspective |
|
|
| @overload |
| def extrinsics_to_view(extrinsics: numpy_.ndarray) -> numpy_.ndarray: |
| """OpenCV camera extrinsics to OpenGL view matrix |
| |
| ## Parameters |
| extrinsics (ndarray): [..., 4, 4] OpenCV camera extrinsics matrix |
| |
| ## Returns |
| (ndarray): [..., 4, 4] OpenGL view matrix""" |
| utils3d.numpy.transforms.extrinsics_to_view |
|
|
| @overload |
| def view_to_extrinsics(view: numpy_.ndarray) -> numpy_.ndarray: |
| """OpenGL view matrix to OpenCV camera extrinsics |
| |
| ## Parameters |
| view (ndarray): [..., 4, 4] OpenGL view matrix |
| |
| ## Returns |
| (ndarray): [..., 4, 4] OpenCV camera extrinsics matrix""" |
| utils3d.numpy.transforms.view_to_extrinsics |
|
|
| @overload |
| def normalize_intrinsics(intrinsics: numpy_.ndarray, size: Union[Tuple[numbers.Number, numbers.Number], numpy_.ndarray], pixel_convention: Literal['integer-center', 'integer-corner'] = 'integer-center') -> numpy_.ndarray: |
| """Normalize intrinsics from pixel cooridnates to uv coordinates |
| |
| ## Parameters |
| - `intrinsics` (ndarray): `(..., 3, 3)` camera intrinsics to normalize |
| - `size` (tuple | ndarray): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `pixel_convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - For more definitions, please refer to `pixel_coord_map()` |
| |
| ## Returns |
| `(ndarray)`: `(..., 3, 3)` normalized camera intrinsics(s)""" |
| utils3d.numpy.transforms.normalize_intrinsics |
|
|
| @overload |
| def denormalize_intrinsics(intrinsics: numpy_.ndarray, size: Union[Tuple[numbers.Number, numbers.Number], numpy_.ndarray], pixel_convention: Literal['integer-center', 'integer-corner'] = 'integer-center') -> numpy_.ndarray: |
| """Denormalize intrinsics from uv cooridnates to pixel coordinates |
| |
| ## Parameters |
| - `intrinsics` (ndarray): `(..., 3, 3)` camera intrinsics to denormalize |
| - `size` (tuple | ndarray): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `pixel_convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - For more definitions, please refer to `pixel_coord_map()` |
| |
| ## Returns |
| `(ndarray)`: `(..., 3, 3)` denormalized camera intrinsics in pixel coordinates""" |
| utils3d.numpy.transforms.denormalize_intrinsics |
|
|
| @overload |
| def crop_intrinsics(intrinsics: numpy_.ndarray, size: Union[Tuple[numbers.Number, numbers.Number], numpy_.ndarray], cropped_top: Union[numbers.Number, numpy_.ndarray], cropped_left: Union[numbers.Number, numpy_.ndarray], cropped_height: Union[numbers.Number, numpy_.ndarray], cropped_width: Union[numbers.Number, numpy_.ndarray]) -> numpy_.ndarray: |
| """Evaluate the new intrinsics after cropping the image |
| |
| ## Parameters |
| - `intrinsics` (ndarray): (..., 3, 3) camera intrinsics(s) to crop |
| - `size` (tuple | ndarray): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `cropped_top` (int | ndarray): (...) top pixel index of the cropped image(s) |
| - `cropped_left` (int | ndarray): (...) left pixel index of the cropped image(s) |
| - `cropped_height` (int | ndarray): (...) height of the cropped image(s) |
| - `cropped_width` (int | ndarray): (...) width of the cropped image(s) |
| |
| ## Returns |
| (ndarray): (..., 3, 3) cropped camera intrinsics""" |
| utils3d.numpy.transforms.crop_intrinsics |
|
|
| @overload |
| def pixel_to_uv(pixel: numpy_.ndarray, size: Union[Tuple[numbers.Number, numbers.Number], numpy_.ndarray], pixel_convention: Literal['integer-center', 'integer-corner'] = 'integer-center') -> numpy_.ndarray: |
| """Convert pixel space coordiantes to UV space coordinates. |
| |
| ## Parameters |
| - `pixel` (ndarray): `(..., 2)` pixel coordinrates |
| - `size` (tuple | ndarray): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `pixel_convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - For more definitions, please refer to `pixel_coord_map()` |
| |
| ## Returns |
| (ndarray): `(..., 2)` uv coordinrates""" |
| utils3d.numpy.transforms.pixel_to_uv |
|
|
| @overload |
| def pixel_to_ndc(pixel: numpy_.ndarray, size: Union[Tuple[numbers.Number, numbers.Number], numpy_.ndarray], pixel_convention: Literal['integer-center', 'integer-corner'] = 'integer-center') -> numpy_.ndarray: |
| """Convert pixel coordinates to NDC (Normalized Device Coordinates). |
| |
| ## Parameters |
| - `pixel` (ndarray): `(..., 2)` pixel coordinrates. |
| - `size` (tuple | ndarray): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `pixel_convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates represent pixel centers or corners. Defaults to 'integer-center'. |
| - For more definitions, please refer to `pixel_coord_map()` |
| |
| ## Returns |
| (ndarray): `(..., 2)` ndc coordinrates, the range is (-1, 1)""" |
| utils3d.numpy.transforms.pixel_to_ndc |
|
|
| @overload |
| def uv_to_pixel(uv: numpy_.ndarray, size: Union[Tuple[numbers.Number, numbers.Number], numpy_.ndarray], pixel_convention: Literal['integer-center', 'integer-corner'] = 'integer-center') -> numpy_.ndarray: |
| """Convert UV space coordinates to pixel space coordinates. |
| |
| ## Parameters |
| - `uv` (ndarray): `(..., 2)` uv coordinrates. |
| - `size` (tuple | ndarray): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `pixel_convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - For more definitions, please refer to `pixel_coord_map()` |
| |
| ## Returns |
| (ndarray): `(..., 2)` pixel coordinrates""" |
| utils3d.numpy.transforms.uv_to_pixel |
|
|
| @overload |
| def depth_linear_to_buffer(depth: numpy_.ndarray, near: Union[float, numpy_.ndarray], far: Union[float, numpy_.ndarray]) -> numpy_.ndarray: |
| """Project linear depth to depth value in screen space |
| |
| ## Parameters |
| depth (ndarray): [...] depth value |
| near (float | ndarray): [...] near plane to clip |
| far (float | ndarray): [...] far plane to clip |
| |
| ## Returns |
| (ndarray): [..., 1] depth value in screen space, value ranging in [0, 1]""" |
| utils3d.numpy.transforms.depth_linear_to_buffer |
|
|
| @overload |
| def depth_buffer_to_linear(depth_buffer: numpy_.ndarray, near: Union[float, numpy_.ndarray], far: Union[float, numpy_.ndarray]) -> numpy_.ndarray: |
| """OpenGL depth buffer to linear depth |
| |
| ## Parameters |
| depth_buffer (ndarray): [...] depth value |
| near (float | ndarray): [...] near plane to clip |
| far (float | ndarray): [...] far plane to clip |
| |
| ## Returns |
| (ndarray): [..., 1] linear depth""" |
| utils3d.numpy.transforms.depth_buffer_to_linear |
|
|
| @overload |
| def unproject_cv(uv: numpy_.ndarray, depth: numpy_.ndarray, intrinsics: numpy_.ndarray, extrinsics: numpy_.ndarray = None) -> numpy_.ndarray: |
| """Unproject uv coordinates to 3D view space following the OpenCV convention |
| |
| ## Parameters |
| uv (ndarray): [..., N, 2] uv coordinates, value ranging in [0, 1]. |
| The origin (0., 0.) is corresponding to the left & top |
| depth (ndarray): [..., N] depth value |
| extrinsics (ndarray): [..., 4, 4] extrinsics matrix |
| intrinsics (ndarray): [..., 3, 3] intrinsics matrix |
| |
| ## Returns |
| points (ndarray): [..., N, 3] 3d points""" |
| utils3d.numpy.transforms.unproject_cv |
|
|
| @overload |
| def unproject_gl(uv: numpy_.ndarray, depth: numpy_.ndarray, projection: numpy_.ndarray, view: Optional[numpy_.ndarray] = None) -> numpy_.ndarray: |
| """Unproject screen space coordinates to 3D view space following the OpenGL convention (except for row major matrices) |
| |
| ## Parameters |
| uv (ndarray): (..., N, 2) screen space XY coordinates, value ranging in [0, 1]. |
| The origin (0., 0.) is corresponding to the left & bottom |
| depth (ndarray): (..., N) linear depth values |
| projection (ndarray): (..., 4, 4) projection matrix |
| view (ndarray): (..., 4, 4) view matrix |
| |
| ## Returns |
| points (ndarray): (..., N, 3) 3d points""" |
| utils3d.numpy.transforms.unproject_gl |
|
|
| @overload |
| def project_cv(points: numpy_.ndarray, intrinsics: numpy_.ndarray, extrinsics: Optional[numpy_.ndarray] = None) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Project 3D points to 2D following the OpenCV convention |
| |
| ## Parameters |
| points (ndarray): [..., N, 3] |
| extrinsics (ndarray): [..., 4, 4] extrinsics matrix |
| intrinsics (ndarray): [..., 3, 3] intrinsics matrix |
| |
| ## Returns |
| uv_coord (ndarray): [..., N, 2] uv coordinates, value ranging in [0, 1]. |
| The origin (0., 0.) is corresponding to the left & top |
| linear_depth (ndarray): [..., N] linear depth""" |
| utils3d.numpy.transforms.project_cv |
|
|
| @overload |
| def project_gl(points: numpy_.ndarray, projection: numpy_.ndarray, view: numpy_.ndarray = None) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Project 3D points to 2D following the OpenGL convention (except for row major matrices) |
| |
| ## Parameters |
| points (ndarray): [..., N, 3] or [..., N, 4] 3D points to project, if the last |
| dimension is 4, the points are assumed to be in homogeneous coordinates |
| view (ndarray): [..., 4, 4] view matrix |
| projection (ndarray): [..., 4, 4] projection matrix |
| |
| ## Returns |
| scr_coord (ndarray): [..., N, 2] OpenGL screen space XY coordinates, value ranging in [0, 1]. |
| The origin (0., 0.) is corresponding to the left & bottom |
| linear_depth (ndarray): [..., N] linear depth""" |
| utils3d.numpy.transforms.project_gl |
|
|
| @overload |
| def project(points: numpy_.ndarray, *, intrinsics: Optional[numpy_.ndarray] = None, extrinsics: Optional[numpy_.ndarray] = None, view: Optional[numpy_.ndarray] = None, projection: Optional[numpy_.ndarray] = None) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Calculate projection. |
| - For OpenCV convention, use `intrinsics` and `extrinsics` matrices. |
| - For OpenGL convention, use `view` and `projection` matrices. |
| |
| ## Parameters |
| |
| - `points`: (..., N, 3) 3D world-space points |
| - `intrinsics`: (..., 3, 3) intrinsics matrix |
| - `extrinsics`: (..., 4, 4) extrinsics matrix |
| - `view`: (..., 4, 4) view matrix |
| - `projection`: (..., 4, 4) projection matrix |
| |
| ## Returns |
| |
| - `uv`: (..., N, 2) 2D coordinates. |
| - For OpenCV convention, it is the normalized image coordinate where (0, 0) is the top left corner. |
| - For OpenGL convention, it is the screen space XY coordinate where (0, 0) is the bottom left corner. |
| - `depth`: (..., N) linear depth values, where `depth > 0` is visible. |
| - For OpenCV convention, it is the Z coordinate in camera space. |
| - For OpenGL convention, it is the -Z coordinate in camera space.""" |
| utils3d.numpy.transforms.project |
|
|
| @overload |
| def unproject(uv: numpy_.ndarray, depth: Optional[numpy_.ndarray], *, intrinsics: Optional[numpy_.ndarray] = None, extrinsics: Optional[numpy_.ndarray] = None, projection: Optional[numpy_.ndarray] = None, view: Optional[numpy_.ndarray] = None) -> numpy_.ndarray: |
| """Calculate inverse projection. |
| - For OpenCV convention, use `intrinsics` and `extrinsics` matrices. |
| - For OpenGL convention, use `view` and `projection` matrices. |
| |
| ## Parameters |
| |
| - `uv`: (..., N, 2) 2D coordinates. |
| - For OpenCV convention, it is the normalized image coordinate where (0, 0) is the top left corner. |
| - For OpenGL convention, it is the screen space XY coordinate where (0, 0) is the bottom left corner. |
| - `depth`: (..., N) linear depth values, where `depth > 0` is visible. |
| - For OpenCV convention, it is the Z coordinate in camera space. |
| - For OpenGL convention, it is the -Z coordinate in camera space. |
| - `intrinsics`: (..., 3, 3) intrinsics matrix |
| - `extrinsics`: (..., 4, 4) extrinsics matrix |
| - `view`: (..., 4, 4) view matrix |
| - `projection`: (..., 4, 4) projection matrix |
| |
| ## Returns |
| |
| - `points`: (..., N, 3) 3D world-space points""" |
| utils3d.numpy.transforms.unproject |
|
|
| @overload |
| def screen_coord_to_view_coord(screen_coord: numpy_.ndarray, projection: numpy_.ndarray) -> numpy_.ndarray: |
| """Unproject screen space coordinates to 3D view space following the OpenGL convention (except for row major matrices) |
| |
| ## Parameters |
| screen_coord (ndarray): (..., N, 3) screen space XYZ coordinates, value ranging in [0, 1] |
| The origin (0., 0.) is corresponding to the left & bottom |
| projection (ndarray): (..., 4, 4) projection matrix |
| |
| ## Returns |
| points (ndarray): [..., N, 3] 3d points in view space""" |
| utils3d.numpy.transforms.screen_coord_to_view_coord |
|
|
| @overload |
| def quaternion_to_matrix(quaternion: numpy_.ndarray) -> numpy_.ndarray: |
| """Converts a batch of quaternions (w, x, y, z) to rotation matrices |
| |
| ## Parameters |
| quaternion (ndarray): shape (..., 4), the quaternions to convert |
| |
| ## Returns |
| ndarray: shape (..., 3, 3), the rotation matrices corresponding to the given quaternions""" |
| utils3d.numpy.transforms.quaternion_to_matrix |
|
|
| @overload |
| def quaternion_multiply(q1: numpy_.ndarray, q2: numpy_.ndarray) -> numpy_.ndarray: |
| """Multiplies two quaternions (w, x, y, z) |
| |
| Parameters |
| ---- |
| q1 (ndarray): shape (..., 4), the first quaternion |
| q2 (ndarray): shape (..., 4), the second quaternion |
| |
| Returns |
| ---- |
| ndarray: shape (..., 4), the product of the two quaternions""" |
| utils3d.numpy.transforms.quaternion_multiply |
|
|
| @overload |
| def quaternion_inverse(quaternion: numpy_.ndarray) -> numpy_.ndarray: |
| """Calculate the inverse of a batch of quaternions (w, x, y, z) |
| |
| Parameters |
| ---- |
| quaternion (ndarray): shape (..., 4), the quaternions to invert |
| |
| Returns |
| ---- |
| ndarray: shape (..., 4)""" |
| utils3d.numpy.transforms.quaternion_inverse |
|
|
| @overload |
| def quaternion_normalize(quaternion: numpy_.ndarray) -> numpy_.ndarray: |
| """Normalize quaternions (w, x, y, z) to unit length and positive w component |
| |
| Parameters |
| ---- |
| quaternion (ndarray): shape (..., 4), the quaternions to normalize |
| |
| Returns |
| ---- |
| ndarray: shape (..., 4), the normalized quaternions with unit length and positive w component""" |
| utils3d.numpy.transforms.quaternion_normalize |
|
|
| @overload |
| def axis_angle_to_matrix(axis_angle: numpy_.ndarray) -> numpy_.ndarray: |
| """Convert axis-angle representation (rotation vector) to rotation matrix, whose direction is the axis of rotation and length is the angle of rotation |
| |
| ## Parameters |
| axis_angle (ndarray): shape (..., 3), axis-angle vcetors |
| |
| ## Returns |
| ndarray: shape (..., 3, 3) The rotation matrices for the given axis-angle parameters""" |
| utils3d.numpy.transforms.axis_angle_to_matrix |
|
|
| @overload |
| def matrix_to_quaternion(rot_mat: numpy_.ndarray) -> numpy_.ndarray: |
| """Convert 3x3 rotation matrix to quaternion (w, x, y, z) |
| |
| ## Parameters |
| rot_mat (ndarray): shape (..., 3, 3), the rotation matrices to convert |
| |
| ## Returns |
| ndarray: shape (..., 4), the quaternions corresponding to the given rotation matrices""" |
| utils3d.numpy.transforms.matrix_to_quaternion |
|
|
| @overload |
| def extrinsics_to_essential(extrinsics: numpy_.ndarray): |
| """extrinsics matrix `[[R, t] [0, 0, 0, 1]]` such that `x' = R (x - t)` to essential matrix such that `x' E x = 0` |
| |
| ## Parameters |
| extrinsics (np.ndaray): [..., 4, 4] extrinsics matrix |
| |
| ## Returns |
| (np.ndaray): [..., 3, 3] essential matrix""" |
| utils3d.numpy.transforms.extrinsics_to_essential |
|
|
| @overload |
| def axis_angle_to_quaternion(axis_angle: numpy_.ndarray) -> numpy_.ndarray: |
| """Convert axis-angle representation (rotation vector) to quaternion (w, x, y, z) |
| |
| ## Parameters |
| axis_angle (ndarray): shape (..., 3), axis-angle vcetors |
| |
| ## Returns |
| ndarray: shape (..., 4) The quaternions for the given axis-angle parameters""" |
| utils3d.numpy.transforms.axis_angle_to_quaternion |
|
|
| @overload |
| def euler_axis_angle_rotation(axis: str, angle: numpy_.ndarray) -> numpy_.ndarray: |
| """Return the rotation matrices for one of the rotations about an axis |
| of which Euler angles describe, for each value of the angle given. |
| |
| ## Parameters |
| axis: Axis label "X" or "Y or "Z". |
| angle: any shape ndarray of Euler angles in radians |
| |
| ## Returns |
| Rotation matrices as ndarray of shape (..., 3, 3).""" |
| utils3d.numpy.transforms.euler_axis_angle_rotation |
|
|
| @overload |
| def euler_angles_to_matrix(euler_angles: numpy_.ndarray, convention: str = 'XYZ') -> numpy_.ndarray: |
| """Convert rotations given as Euler angles in radians to rotation matrices. |
| |
| ## Parameters |
| euler_angles: Euler angles in radians as ndarray of shape (..., 3), XYZ |
| convention: permutation of "X", "Y" or "Z", representing the order of Euler rotations to apply. |
| |
| ## Returns |
| Rotation matrices as ndarray of shape (..., 3, 3).""" |
| utils3d.numpy.transforms.euler_angles_to_matrix |
|
|
| @overload |
| def matrix_to_axis_angle(rot_mat: numpy_.ndarray) -> numpy_.ndarray: |
| """Convert a batch of 3x3 rotation matrices to axis-angle representation (rotation vector) |
| |
| ## Parameters |
| rot_mat (ndarray): shape (..., 3, 3), the rotation matrices to convert |
| |
| ## Returns |
| ndarray: shape (..., 3), the axis-angle vectors corresponding to the given rotation matrices""" |
| utils3d.numpy.transforms.matrix_to_axis_angle |
|
|
| @overload |
| def matrix_to_euler_angles(matrix: numpy_.ndarray, convention: str) -> numpy_.ndarray: |
| """Convert rotations given as rotation matrices to Euler angles in radians. |
| NOTE: The composition order eg. `XYZ` means `Rz * Ry * Rx` (like blender), instead of `Rx * Ry * Rz` (like pytorch3d) |
| |
| ## Parameters |
| matrix: Rotation matrices as ndarray of shape (..., 3, 3). |
| convention: Convention string of three uppercase letters. |
| |
| ## Returns |
| Euler angles in radians as ndarray of shape (..., 3), in the order of XYZ (like blender), instead of convention (like pytorch3d)""" |
| utils3d.numpy.transforms.matrix_to_euler_angles |
|
|
| @overload |
| def quaternion_to_axis_angle(quaternion: numpy_.ndarray) -> numpy_.ndarray: |
| """Convert a batch of quaternions (w, x, y, z) to axis-angle representation (rotation vector) |
| |
| ## Parameters |
| quaternion (ndarray): shape (..., 4), the quaternions to convert |
| |
| ## Returns |
| ndarray: shape (..., 3), the axis-angle vectors corresponding to the given quaternions""" |
| utils3d.numpy.transforms.quaternion_to_axis_angle |
|
|
| @overload |
| def skew_symmetric(v: numpy_.ndarray): |
| """Skew symmetric matrix from a 3D vector""" |
| utils3d.numpy.transforms.skew_symmetric |
|
|
| @overload |
| def rotation_matrix_from_vectors(v1: numpy_.ndarray, v2: numpy_.ndarray): |
| """Rotation matrix that rotates v1 to v2""" |
| utils3d.numpy.transforms.rotation_matrix_from_vectors |
|
|
| @overload |
| def ray_intersection(p1: numpy_.ndarray, d1: numpy_.ndarray, p2: numpy_.ndarray, d2: numpy_.ndarray): |
| """Compute the intersection/closest point of two D-dimensional rays |
| If the rays are intersecting, the closest point is the intersection point. |
| |
| ## Parameters |
| p1 (ndarray): (..., D) origin of ray 1 |
| d1 (ndarray): (..., D) direction of ray 1 |
| p2 (ndarray): (..., D) origin of ray 2 |
| d2 (ndarray): (..., D) direction of ray 2 |
| |
| ## Returns |
| (ndarray): (..., N) intersection point""" |
| utils3d.numpy.transforms.ray_intersection |
|
|
| @overload |
| def make_affine_matrix(M: numpy_.ndarray, t: numpy_.ndarray) -> numpy_.ndarray: |
| """Make an affine transformation matrix from a linear matrix and a translation vector. |
| |
| ## Parameters |
| M (ndarray): [..., D, D] linear matrix (rotation, scaling or general deformation) |
| t (ndarray): [..., D] translation vector |
| |
| ## Returns |
| ndarray: [..., D + 1, D + 1] affine transformation matrix""" |
| utils3d.numpy.transforms.make_affine_matrix |
|
|
| @overload |
| def random_rotation_matrix(*size: int, dtype=numpy_.float32) -> numpy_.ndarray: |
| """Generate random 3D rotation matrix. |
| |
| ## Parameters |
| dtype: The data type of the output rotation matrix. |
| |
| ## Returns |
| ndarray: `(*size, 3, 3)` random rotation matrix.""" |
| utils3d.numpy.transforms.random_rotation_matrix |
|
|
| @overload |
| def lerp(x1: numpy_.ndarray, x2: numpy_.ndarray, t: numpy_.ndarray) -> numpy_.ndarray: |
| """Linear interpolation between two vectors. |
| |
| ## Parameters |
| x1 (ndarray): [..., D] vector 1 |
| x2 (ndarray): [..., D] vector 2 |
| t (ndarray): [..., N] interpolation parameter. [0, 1] for interpolation between x1 and x2, otherwise for extrapolation. |
| |
| ## Returns |
| ndarray: [..., N, D] interpolated vector""" |
| utils3d.numpy.transforms.lerp |
|
|
| @overload |
| def slerp(v1: numpy_.ndarray, v2: numpy_.ndarray, t: numpy_.ndarray) -> numpy_.ndarray: |
| """Spherical linear interpolation between two (unit) vectors. |
| |
| ## Parameters |
| - `v1` (ndarray): `(..., D)` (unit) vector 1 |
| - `v2` (ndarray): `(..., D)` (unit) vector 2 |
| - `t` (ndarray): `(..., N)` interpolation parameter in [0, 1] |
| |
| ## Returns |
| ndarray: `(..., N, D)` interpolated unit vector""" |
| utils3d.numpy.transforms.slerp |
|
|
| @overload |
| def slerp_rotation_matrix(R1: numpy_.ndarray, R2: numpy_.ndarray, t: numpy_.ndarray) -> numpy_.ndarray: |
| """Spherical linear interpolation between two rotation matrices. |
| |
| ## Parameters |
| - `R1` (ndarray): [..., 3, 3] rotation matrix 1 |
| - `R2` (ndarray): [..., 3, 3] rotation matrix 2 |
| - `t` (ndarray): [..., N] interpolation parameter in [0, 1] |
| |
| ## Returns |
| ndarray: [...,N, 3, 3] interpolated rotation matrix""" |
| utils3d.numpy.transforms.slerp_rotation_matrix |
|
|
| @overload |
| def interpolate_se3_matrix(T1: numpy_.ndarray, T2: numpy_.ndarray, t: numpy_.ndarray) -> numpy_.ndarray: |
| """Linear interpolation between two SE(3) matrices. |
| |
| ## Parameters |
| - `T1` (ndarray): [..., 4, 4] SE(3) matrix 1 |
| - `T2` (ndarray): [..., 4, 4] SE(3) matrix 2 |
| - `t` (ndarray): [..., N] interpolation parameter in [0, 1] |
| |
| ## Returns |
| ndarray: [..., N, 4, 4] interpolated SE(3) matrix""" |
| utils3d.numpy.transforms.interpolate_se3_matrix |
|
|
| @overload |
| def piecewise_lerp(x: numpy_.ndarray, t: numpy_.ndarray, s: numpy_.ndarray, extrapolation_mode: Literal['constant', 'linear'] = 'constant') -> numpy_.ndarray: |
| """Linear spline interpolation. |
| |
| ## Parameters |
| - `x`: ndarray, shape (n, d): the values of data points. |
| - `t`: ndarray, shape (n,): the times of the data points. |
| - `s`: ndarray, shape (m,): the times to be interpolated. |
| - `extrapolation_mode`: str, the mode of extrapolation. 'constant' means extrapolate the boundary values, 'linear' means extrapolate linearly. |
| |
| ## Returns |
| - `y`: ndarray, shape (..., m, d): the interpolated values.""" |
| utils3d.numpy.transforms.piecewise_lerp |
|
|
| @overload |
| def piecewise_interpolate_se3_matrix(T: numpy_.ndarray, t: numpy_.ndarray, s: numpy_.ndarray, extrapolation_mode: Literal['constant', 'linear'] = 'constant') -> numpy_.ndarray: |
| """Linear spline interpolation for SE(3) matrices. |
| |
| ## Parameters |
| - `T`: ndarray, shape (n, 4, 4): the SE(3) matrices. |
| - `t`: ndarray, shape (n,): the times of the data points. |
| - `s`: ndarray, shape (m,): the times to be interpolated. |
| - `extrapolation_mode`: str, the mode of extrapolation. 'constant' means extrapolate the boundary values, 'linear' means extrapolate linearly. |
| |
| ## Returns |
| - `T_interp`: ndarray, shape (..., m, 4, 4): the interpolated SE(3) matrices.""" |
| utils3d.numpy.transforms.piecewise_interpolate_se3_matrix |
|
|
| @overload |
| def transform_points(x: numpy_.ndarray, *Ts: numpy_.ndarray) -> numpy_.ndarray: |
| """Apply transformation(s) to a point or a set of points. |
| It is like `(Tn @ ... @ T2 @ T1 @ x[:, None]).squeeze(0)`, but: |
| 1. Automatically handle the homogeneous coordinate; |
| - x will be padded with homogeneous coordinate 1. |
| - Each T will be padded by identity matrix to match the dimension. |
| 2. Using efficient contraction path when array sizes are large, based on `einsum`. |
| |
| ## Parameters |
| - `x`: ndarray, shape `(..., D)`: the points to be transformed. |
| - `Ts`: ndarray, shape `(..., D1, D2)`: the affine transformation matrix (matrices) |
| If more than one transformation is given, they will be applied in corresponding order. |
| ## Returns |
| - `y`: ndarray, shape `(..., D)`: the transformed point or a set of points. |
| |
| ## Example Usage |
| |
| - Just linear transformation |
| |
| ``` |
| y = transform(x_3, mat_3x3) |
| ``` |
| |
| - Affine transformation |
| |
| ``` |
| y = transform(x_3, mat_3x4) |
| ``` |
| |
| - Chain multiple transformations |
| |
| ``` |
| y = transform(x_3, T1_4x4, T2_3x4, T3_3x4) |
| ```""" |
| utils3d.numpy.transforms.transform_points |
|
|
| @overload |
| def angle_between(v1: numpy_.ndarray, v2: numpy_.ndarray): |
| """Calculate the angle between two (batches of) vectors. |
| Better precision than using the arccos dot product directly. |
| |
| ## Parameters |
| - `v1`: ndarray, shape (..., D): the first vector. |
| - `v2`: ndarray, shape (..., D): the second vector. |
| |
| ## Returns |
| `angle`: ndarray, shape (...): the angle between the two vectors.""" |
| utils3d.numpy.transforms.angle_between |
|
|
| @overload |
| def kabasch(cov: numpy_.ndarray) -> numpy_.ndarray: |
| utils3d.numpy.pose.kabasch |
|
|
| @overload |
| def umeyama(cov_yx: numpy_.ndarray, cov_xx: Optional[numpy_.ndarray] = None, cov_yy: Optional[numpy_.ndarray] = None, mean_x: Optional[numpy_.ndarray] = None, mean_y: Optional[numpy_.ndarray] = None) -> Tuple[numpy_.ndarray, numpy_.ndarray, numpy_.ndarray]: |
| """Procrustes analysis to solve for scale `s`, rotation `R` and translation `t` such that `y_i ~= s R x_i + t`. |
| |
| Parameters |
| ---- |
| - `cov_yx`: (..., 3, 3) covariance matrix between y and x points. |
| - `cov_xx`: (..., 3, 3) covariance matrix of x points. If None, no scaling is solved. |
| - `cov_yy`: (..., 3, 3) covariance matrix of y points. If None, no scaling is solved. |
| - `mean_x`: (..., 3) mean of x points. If None, no translation is solved. |
| - `mean_y`: (..., 3) mean of y points. If None, no translation is solved. |
| |
| Specifically, based on provided inputs: |
| |
| - To solve the rotation `R`, `cov_yx` must be given. |
| - To solve the scale `s`, at least one of `cov_xx` and `cov_yy` must be given. |
| - (Recommended) If both `cov_xx` and `cov_yy` are given, the scale will be solved by minimizing a symmetric cost: |
| `||s R X + t - Y||_F^2 / ||Y||_F^2 + ||s R^T (Y - t) - X||_F^2 / ||X||_F^2` |
| - If only `cov_xx` is given, the scale will be solved by minimizing forward cost |
| `||s R X + t - Y||_F^2` |
| - If only `cov_yy` is given, the scale will be solved by minimizing inverse cost |
| `||s R^T (Y - t) - X||_F^2` |
| - To solve the translation `t`, provide `mean_x` and `mean_y`. |
| |
| Returns |
| ---- |
| - `s`: (...) scale factor. None if both cov_xx and cov_yy are None. |
| - `R`: (..., 3, 3) rotation matrix. |
| - `t`: (..., 3) translation vector. None if mean_x or mean_y is None.""" |
| utils3d.numpy.pose.umeyama |
|
|
| @overload |
| def affine_umeyama(cov_yx: numpy_.ndarray, cov_xx: numpy_.ndarray, cov_yy: numpy_.ndarray, mean_x: numpy_.ndarray, mean_y: numpy_.ndarray, lam: float = 0.01, niter: int = 8) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Extended Procrustes analysis to solve for affine transformation `A` and translation `t` such that `y_i ~= A x_i + t`. |
| |
| Parameters |
| ---- |
| - `cov_yx`: (..., 3, 3) covariance matrix between y |
| - `cov_xx`: (..., 3, 3) covariance matrix of x points. |
| - `cov_yy`: (..., 3, 3) covariance matrix of y |
| - `mean_x`: (..., 3) mean of x points. |
| - `mean_y`: (..., 3) mean of y points. |
| - `lam`: rigidity regularization weight. |
| - `gamma`: symmetricity regularization annealing factor. |
| - `niter`: number of iterations for solving. |
| |
| Returns |
| ---- |
| - `A`: (..., 3, 3) affine transformation matrix. |
| - `t`: (..., 3) translation vector.""" |
| utils3d.numpy.pose.affine_umeyama |
|
|
| @overload |
| def solve_pose(p: numpy_.ndarray, q: numpy_.ndarray, w: Optional[numpy_.ndarray] = None, *, mode: Literal['rigid', 'similar', 'affine'] = 'rigid', lam: float = 0.01, niter: int = 5) -> numpy_.ndarray: |
| """Solve for the pose (transformation from p to q) given weighted point correspondences. |
| |
| Parameters |
| ---- |
| - `p`: (..., N, 3) source points |
| - `q`: (..., N, 3) target points |
| - `w`: optional (..., N) weights for each point correspondence. If None, uniform weights are used. |
| - `mode`: mode of transformation to apply. Can be 'rigid', 'similar', or 'affine'. |
| - For 'rigid', only rotation and translation are allowed. |
| - For 'similar', uniform scaling, rotation and translation are allowed. |
| - For 'affine', full affine transformation is allowed. Using least squares. |
| - `lam`: regularization weight for 'affine' mode. |
| - `niter`: number of iterations for 'affine' mode. |
| |
| Returns |
| ---- |
| - `pose`: (..., 4, 4) transformations matrix from p to q.""" |
| utils3d.numpy.pose.solve_pose |
|
|
| @overload |
| def segment_solve_pose(p: numpy_.ndarray, q: numpy_.ndarray, w: Optional[numpy_.ndarray] = None, *, offsets: numpy_.ndarray, mode: Literal['rigid', 'similar', 'affine'] = 'rigid', lam: float = 0.01, niter: int = 5) -> numpy_.ndarray: |
| """Solve for the pose (transformation from p to q) given weighted point correspondences. |
| |
| Parameters |
| ---- |
| - `p`: (N, 3) source points |
| - `q`: (N, 3) target points |
| - `w`: (N,) weights for each point correspondence |
| - `offsets`: (S + 1,) segment offsets. Points in each segment belong to the same rigid / affine body. |
| - `mode`: mode of transformation to apply. Can be 'rigid', 'similar', or 'affine'. |
| - For 'rigid', only rotation and translation are allowed. |
| - For 'similar', uniform scaling, rotation and translation are allowed. |
| - For 'affine', full affine transformation is allowed. Using least squares. |
| - `lam`: regularization weight for 'affine' mode. |
| - `niter`: number of iterations for 'affine' mode. |
| |
| Returns |
| ---- |
| - `pose`: (S, 4, 4) transformations matrix from p to q.""" |
| utils3d.numpy.pose.segment_solve_pose |
|
|
| @overload |
| def solve_poses_sequential(trajectories: numpy_.ndarray, weights: Optional[numpy_.ndarray] = None, *, accum: Optional[Tuple[numpy_.ndarray, ...]] = None, min_valid_size: int = 3, mode: Literal['rigid', 'similar', 'affine'] = 'rigid', lam: float = 0.01, niter: int = 8) -> Tuple[numpy_.ndarray, Tuple[numpy_.ndarray, ...], Tuple[numpy_.ndarray, numpy_.ndarray, numpy_.ndarray, numpy_.ndarray]]: |
| """Given trajectories of points over time, sequentially solve for the poses (transformations from canonical to each frame) of each body at each frame. |
| |
| Parameters |
| ---- |
| - `trajectories`: (T, ..., N, 3) posed points. T is number of frames. `...` is optional batch dimensions. N is number of points per group. |
| - `weights`: (T, ..., N) quardratic error term weights for each point at each frame |
| - `accum`: accumulated statistics from previous calls. If None, start fresh. |
| - `min_valid_size`: minimum number of valid points in each frame to consider the segment / group valid. |
| - `mode`: mode of transformation to apply. Can be 'rigid', 'similar', or 'affine'. |
| - For 'rigid', only rotation and translation are allowed. |
| - For 'similar', uniform scaling, rotation and translation are allowed. |
| - For 'affine', full affine transformation is allowed. Using least squares. |
| - `lam`: rigidity regularization weight for 'affine' mode. |
| - `niter`: number of iterations for 'affine' mode. |
| |
| Returns |
| ---- |
| - `poses`: (T, ..., 4, 4) transformations from canonical to each frame. |
| - `valid`: (T, ...) boolean mask indicating valid segments |
| - `stats`: canonical statistics of each group, |
| It is a tuple of: |
| - `mu`: (..., 3) weighted mean of points |
| - `cov`: (..., 3, 3) weighted covariance of points |
| - `tot_w`: (...,) total weight of points |
| - `nnz`: (...,) number of non-zero weight points |
| - `canonical_points`: (..., N, 3) canonical points. |
| - `err`: (..., N,) per-point RMS error over all time := sqrt(sum_over_time(per_point_weights * per_point_squared_error) / per_point_nnz) |
| Use this to filter outliers as needed. |
| - `accum`: per point accumulated statistics. Just pass it to the next call for incremental solving. |
| It is a tuple of: |
| - `accum_sqrtw`: (..., N,) sum of sqrt(weights) |
| - `accum_sqrtwx`: (..., N, 3) sum of sqrt(weights) * x |
| - `accum_sqrtwxx`: (...N, 3, 3) sum of sqrt(weights) * outer(x - mean_sqrtwx, x - mean_sqrtwx) |
| - `accum_w`: (..., N,) sum of weights |
| - `accum_wx`: (..., N, 3) sum of weights * x |
| - `accum_wxx`: (..., N, 3, 3) sum of weights * outer(x - mean_wx, x - mean_wx) |
| - `accum_nnz`: (..., N,) number of non-zero weight accumulations |
| |
| Example |
| ---- |
| ``` |
| accum = None |
| poses, valid = [], [] |
| for new_trajectories_chunk in data_stream: |
| # new_trajectories_chunk: (T_chunk, N, 3) |
| poses_chunk, valid_chunk, stats, canonical_points, err, accum = solve_poses( |
| new_trajectories_chunk, |
| accum=accum, |
| ) |
| poses.append(poses_chunk) |
| valid.append(valid_chunk) |
| # `stats`, `canonical_points` and `err` are returned and updated every chunk. |
| poses = np.concatenate(poses, axis=0) # (T_all, 4, 4), poses over all frames |
| valid = np.concatenate(valid, axis=0) # (T_all,), poses' validity over all frames""" |
| utils3d.numpy.pose.solve_poses_sequential |
|
|
| @overload |
| def segment_solve_poses_sequential(trajectories: numpy_.ndarray, weights: Optional[numpy_.ndarray] = None, offsets: numpy_.ndarray = None, *, accum: Optional[Tuple[numpy_.ndarray, ...]] = None, min_valid_size: int = 3, mode: Literal['rigid', 'similar', 'affine'] = 'rigid', lam: float = 0.01, niter: int = 8) -> Tuple[numpy_.ndarray, Tuple[numpy_.ndarray, ...], Tuple[numpy_.ndarray, numpy_.ndarray, numpy_.ndarray, numpy_.ndarray]]: |
| """Segment array mode for `solve_poses_sequential`. |
| |
| Parameters |
| ---- |
| - `trajectories`: (T, N, 3) posed points. |
| - `weights`: (T, N) quardratic error term weights for each point at each frame |
| - `offsets`: (S + 1,) segment offsets. Points in each segment belong to the same rigid / affine body. |
| - `accum`: accumulated statistics from previous calls. If None, start fresh. |
| - `min_valid_size`: minimum number of valid points in each frame to consider the segment / group valid. |
| - `mode`: mode of transformation to apply. Can be 'rigid', 'similar', or 'affine'. |
| - For 'rigid', only rotation and translation are allowed. |
| - For 'similar', uniform scaling, rotation and translation are allowed. |
| - For 'affine', full affine transformation is allowed. Using least squares. |
| - `lam`: rigidity regularization weight for 'affine' mode. |
| - `niter`: number of iterations for 'affine' mode. |
| |
| Returns |
| ---- |
| - `poses`: (T, S, 4, 4) transformations from canonical to each frame. |
| - `valid`: (T, S) boolean mask indicating valid segments |
| - `stats`: canonical statistics of each group, |
| It is a tuple of: |
| - `mu`: (S, 3) weighted mean of points |
| - `cov`: (S, 3, 3) weighted covariance of points |
| - `tot_w`: (S,) total weight of points |
| - `nnz`: (S,) number of non-zero weight points |
| - `canonical_points`: (N, 3) canonical points. |
| - `err`: (N,) per-point RMS error over all time := sqrt(sum_over_time(per_point_weights * per_point_squared_error) / per_point_nnz) |
| Use this to filter outliers as needed. |
| - `accum`: per point accumulated statistics. Just pass it to the next call for incremental solving. |
| It is a tuple of: |
| - `accum_sqrtw`: (N,) sum of sqrt(weights) |
| - `accum_sqrtwx`: (N, 3) sum of sqrt(weights) * x |
| - `accum_sqrtwxx`: (N, 3, 3) sum of sqrt(weights) * outer(x - mean_sqrtwx, x - mean_sqrtwx) |
| - `accum_w`: (N,) sum of weights |
| - `accum_wx`: (N, 3) sum of weights * x |
| - `accum_wxx`: (N, 3, 3) sum of weights * outer(x - mean_wx, x - mean_wx) |
| - `accum_nnz`: (N,) number of non-zero weight accumulations""" |
| utils3d.numpy.pose.segment_solve_poses_sequential |
|
|
| @overload |
| def segment_roll(data: numpy_.ndarray, offsets: numpy_.ndarray, shift: int, axis: int = 0) -> numpy_.ndarray: |
| """Roll the data within each segment. |
| |
| Parameters |
| ------ |
| - `data`: (ndarray). |
| - `offsets`: (ndarray) shape `(M + 1,)` the offsets of the segmented data. `M` is the number of segments. Starts with 0 and end with `data.shape[axis]`. |
| - `shift`: (int) the number of places by which elements are shifted. If negative, shift to left. |
| - `axis`: (int) the segment axis to roll along. Default is 0. |
| |
| Returns |
| ------- |
| - `data`: (ndarray) the rolled data, same shape as input.""" |
| utils3d.numpy.segment_ops.segment_roll |
|
|
| @overload |
| def segment_take(data: numpy_.ndarray, offsets: numpy_.ndarray, taking: numpy_.ndarray, axis: int = 0) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Take some segments from a segmented array |
| |
| Parameters |
| ------ |
| - `data`: (ndarray) the segmented data. |
| - `offsets`: (ndarray) shape `(M + 1,)` the offsets of the segmented data. `M` is the number of segments. Starts with 0 and end with `data.shape[axis]`. |
| - `taking`: (ndarray) the indices of segments to take of shape `(K,)`, or boolean mask of shape `(M,)` |
| - `axis`: (int) the segment axis to take along. Default is 0. Other axes are treated as batch dimensions. |
| |
| Returns |
| ------- |
| - `new_data`: (ndarray) the new segmented data. |
| - `new_offsets`: (ndarray) shape `(K + 1,)` the offsets of the new segmented data. `K` is the number of taken segments.""" |
| utils3d.numpy.segment_ops.segment_take |
|
|
| @overload |
| def segment_argmax(data: numpy_.ndarray, offsets: numpy_.ndarray, axis: int = 0) -> numpy_.ndarray: |
| """Compute the argmax of each segment in the segmented data. |
| |
| Parameters |
| ----- |
| - `data`: (ndarray). shape `(..., N, ...)`. `N` is the segment dimension. If `data` may have multiple dimensionsm, extra dimensions are treated as batch dimensions. |
| - `offsets`: (ndarray) shape `(M + 1,)` the offsets of the segmented data |
| - `axis`: (int) the segment axis to compute along. Default is 0. |
| |
| Returns |
| ------- |
| - `argmax_indices`: (ndarray) shape `(..., M, ...)` the argmax indices of each segment along the first dimension. |
| |
| Notes |
| ----- |
| If there are multiple maximum values in a segment, the index of the first one is returned. If a segment is empty, -1 is returned.""" |
| utils3d.numpy.segment_ops.segment_argmax |
|
|
| @overload |
| def segment_argmin(data: numpy_.ndarray, offsets: numpy_.ndarray, axis: int = 0) -> numpy_.ndarray: |
| """Compute the argmin of each segment in the segmented data. |
| |
| Parameters |
| ----- |
| - `data`: (ndarray) shape `(..., N, ...)` the data to compute argmin from. If `data` may have multiple dimensionsm, extra dimensions are treated as batch dimensions. |
| - `offsets`: (ndarray) shape `(M + 1,)` the offsets of the segmented data |
| - `axis`: (int) the segment axis to compute along. Default is 0. |
| |
| Returns |
| ----- |
| - `argmin_indices`: (ndarray) shape `(..., M, ...)` the argmin indices of each segment along the first dimension. |
| |
| Notes |
| ----- |
| If there are multiple minimum values in a segment, the index of the first one is returned. If a segment is empty, -1 is returned.""" |
| utils3d.numpy.segment_ops.segment_argmin |
|
|
| @overload |
| def segment_concatenate(segments: Sequence[Tuple[numpy_.ndarray, numpy_.ndarray]], axis: int = 0) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Concatenate segmented arrays within each segment. All numbers of segments remain the same. |
| |
| Parameters |
| ------ |
| - `segments`: (Sequence[Tuple[ndarray, ndarray]]) A sequence of segmented arrays: |
| - `data`: (ndarray) shape `(..., N_i, ...)` |
| - `offsets`: (ndarray) shape `(M + 1,)` segment offsets. |
| - `axis`: (int) the segment axis. |
| |
| Returns |
| ------- |
| - `data`: (ndarray) shape `(..., sum(N_i), ...)` the concatenated data |
| - `offsets`: (ndarray) shape `(M + 1,)` the offsets of the concatenated segmented data.""" |
| utils3d.numpy.segment_ops.segment_concatenate |
|
|
| @overload |
| def segment_concat(segments: Sequence[Tuple[numpy_.ndarray, numpy_.ndarray]], axis: int = 0) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """(Alias for segment_concatenate). |
| Concatenate segmented arrays within each segment. |
| |
| Parameters |
| ------ |
| - `segments`: (Sequence[Tuple[ndarray, ndarray]]) A sequence of segmented arrays: |
| - `data`: (ndarray) shape `(..., N_i, ...)` |
| - `offsets`: (ndarray) shape `(M + 1,)` segment offsets. |
| - `axis`: (int) the segment axis. |
| |
| Returns |
| ------- |
| - `data`: (ndarray) shape `(N, *data_dims)` the concatenated data |
| - `offsets`: (ndarray) shape `(M + 1,)` the offsets of the concatenated segmented data.""" |
| utils3d.numpy.segment_ops.segment_concat |
|
|
| @overload |
| def segment_chain(segments: Sequence[Tuple[numpy_.ndarray, numpy_.ndarray]], axis: int = 0) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Concatenate segmented arrays in sequence. The number of segments are summed. |
| |
| Parameters |
| ------ |
| - `segments`: (Sequence[Tuple[ndarray, ndarray]]) A sequence of segmente arrays: |
| - `data`: (ndarray) shape `(..., N_i, ...)` |
| - `offsets`: (ndarray) shape `(M + 1,)` segment offsets. |
| - `axis`: (int) the segment axis. |
| |
| Returns |
| ------- |
| - `data`: (ndarray) shape `(..., sum(N_i), ...)` the chain-concatenated data |
| - `offsets`: (ndarray) shape `(sum(M_i) + 1,)` the offsets of the concatenated segmented data.""" |
| utils3d.numpy.segment_ops.segment_chain |
|
|
| @overload |
| def group_as_segments(labels: numpy_.ndarray, data: Optional[numpy_.ndarray] = None, return_inverse: bool = False, return_group_ids: bool = False) -> Tuple[numpy_.ndarray, numpy_.ndarray, numpy_.ndarray]: |
| """Group as segments by labels |
| |
| Parameters |
| ----- |
| - `labels` (ndarray): shape `(N, *label_dims)` array of labels for each data point. Labels can be multi-dimensional. |
| - `data` (ndarray, optional): shape `(N, *data_dims)` array. |
| If None, return the indices in each group instead. |
| |
| Returns |
| ------- |
| Assuming there are `M` difference labels: |
| |
| - `segment_labels`: `(ndarray)` shape `(M, *label_dims)` labels of of each segment |
| - `rearranged_data`: `(ndarray)` shape `(N,)` or `(N, *data_dims)` the rearranged data (or indices) where the same labels are grouped as a continous segment. |
| - `offsets`: `(ndarray)` shape `(M + 1,)` |
| |
| `rearranged_data[offsets[i]:offsets[i + 1]]` corresponding to the i-th segment whose label is `segment_labels[i]`""" |
| utils3d.numpy.segment_ops.group_as_segments |
|
|
| @overload |
| def triangulate_mesh(faces: numpy_.ndarray, vertices: numpy_.ndarray = None, method: Literal['fan', 'strip', 'diagonal'] = 'fan', return_face_indices: bool = False) -> numpy_.ndarray: |
| """Triangulate a polygonal mesh. |
| |
| ## Parameters |
| faces (ndarray): [L, P] polygonal faces |
| vertices (ndarray, optional): [N, 3] 3-dimensional vertices. |
| If given, the triangulation is performed according to the distance |
| between vertices. Defaults to None. |
| method (str, optional): triangulation method. Defaults to 'fan'. |
| - 'fan': connect the first vertex to all other vertex pairs |
| - 'strip': create a triangle strip |
| - 'diagonal': for quad faces only, split according to the shorter diagonal |
| return_face_indices (bool, optional): whether to return the original face indices for each triangle. Defaults to False. |
| |
| ## Returns |
| (ndarray): [L * (P - 2), 3] triangular faces""" |
| utils3d.numpy.mesh.triangulate_mesh |
|
|
| @overload |
| def compute_face_corner_angles(vertices: numpy_.ndarray, faces: Optional[numpy_.ndarray] = None) -> numpy_.ndarray: |
| """Compute face corner angles of a mesh |
| |
| ## Parameters |
| - `vertices` (ndarray): `(..., N, 3)` vertices if `faces` is provided, or `(..., F, P, 3)` if `faces` is None |
| - `faces` (ndarray, optional): `(F, P)` face vertex indices, where P is the number of vertices per face |
| |
| ## Returns |
| - `angles` (ndarray): `(..., F, P)` face corner angles""" |
| utils3d.numpy.mesh.compute_face_corner_angles |
|
|
| @overload |
| def compute_face_corner_normals(vertices: numpy_.ndarray, faces: Optional[numpy_.ndarray] = None, normalize: bool = True) -> numpy_.ndarray: |
| """Compute the face corner normals of a mesh |
| |
| ## Parameters |
| - `vertices` (ndarray): `(..., N, 3)` vertices if `faces` is provided, or `(..., F, P, 3)` if `faces` is None |
| - `faces` (ndarray, optional): `(F, P)` face vertex indices, where P is the number of vertices per face |
| - `normalize` (bool): whether to normalize the normals to unit vectors. If not, the normals are the raw cross products. |
| |
| ## Returns |
| - `normals` (ndarray): (..., F, P, 3) face corner normals""" |
| utils3d.numpy.mesh.compute_face_corner_normals |
|
|
| @overload |
| def compute_face_corner_tangents(vertices: numpy_.ndarray, uv: numpy_.ndarray, faces_vertices: Optional[numpy_.ndarray] = None, faces_uv: Optional[numpy_.ndarray] = None, normalize: bool = True) -> numpy_.ndarray: |
| """Compute the face corner tangent (and bitangent) vectors of a mesh |
| |
| ## Parameters |
| - `vertices` (ndarray): `(..., N, 3)` if `faces` is provided, or `(..., F, P, 3)` if `faces_vertices` is None |
| - `uv` (ndarray): `(..., N, 2)` if `faces` is provided, or `(..., F, P, 2)` if `faces_uv` is None |
| - `faces_vertices` (ndarray, optional): `(F, P)` face vertex indices |
| - `faces_uv` (ndarray, optional): `(F, P)` face UV indices |
| - `normalize` (bool): whether to normalize the tangents to unit vectors. If not, the tangents (dX/du, dX/dv) matches the UV parameterized manifold. |
| |
| ## Returns |
| - `tangents` (ndarray): `(..., F, P, 3, 2)` face corner tangents (and bitangents), |
| where the last dimension represents the tangent and bitangent vectors.""" |
| utils3d.numpy.mesh.compute_face_corner_tangents |
|
|
| @overload |
| def compute_face_normals(vertices: numpy_.ndarray, faces: Optional[numpy_.ndarray] = None) -> numpy_.ndarray: |
| """Compute face normals of a mesh |
| |
| ## Parameters |
| - `vertices` (ndarray): `(..., N, 3)` vertices if `faces` is provided, or `(..., F, P, 3)` if `faces` is None |
| - `faces` (ndarray, optional): `(F, P)` face vertex indices, where P is the number of vertices per face |
| |
| ## Returns |
| - `normals` (ndarray): `(..., F, 3)` face normals. Always normalized.""" |
| utils3d.numpy.mesh.compute_face_normals |
|
|
| @overload |
| def compute_face_tangents(vertices: numpy_.ndarray, uv: numpy_.ndarray, faces_vertices: Optional[numpy_.ndarray] = None, faces_uv: Optional[numpy_.ndarray] = None, normalize: bool = True) -> numpy_.ndarray: |
| """Compute the face corner tangent (and bitangent) vectors of a mesh |
| |
| ## Parameters |
| - `vertices` (ndarray): `(..., N, 3)` if `faces` is provided, or `(..., F, P, 3)` if `faces_vertices` is None |
| - `uv` (ndarray): `(..., N, 2)` if `faces` is provided, or `(..., F, P, 2)` if `faces_uv` is None |
| - `faces_vertices` (ndarray, optional): `(F, P)` face vertex indices |
| - `faces_uv` (ndarray, optional): `(F, P)` face UV indices |
| |
| ## Returns |
| - `tangents` (ndarray): `(..., F, 3, 2)` face corner tangents (and bitangents), |
| where the last dimension represents the tangent and bitangent vectors.""" |
| utils3d.numpy.mesh.compute_face_tangents |
|
|
| @overload |
| def compute_vertex_normals(vertices: numpy_.ndarray, faces: numpy_.ndarray, weighted: Literal['uniform', 'area', 'angle'] = 'uniform') -> numpy_.ndarray: |
| """Compute vertex normals of a triangular mesh by averaging neighboring face normals |
| |
| ## Parameters |
| vertices (ndarray): [..., N, 3] 3-dimensional vertices |
| faces (ndarray): [T, P] face vertex indices, where P is the number of vertices per face |
| |
| ## Returns |
| normals (ndarray): [..., N, 3] vertex normals (already normalized to unit vectors)""" |
| utils3d.numpy.mesh.compute_vertex_normals |
|
|
| @overload |
| def remove_corrupted_faces(faces: numpy_.ndarray) -> numpy_.ndarray: |
| """Remove corrupted faces (faces with duplicated vertices) |
| |
| ## Parameters |
| faces (ndarray): [T, 3] triangular face indices |
| |
| ## Returns |
| ndarray: [T_, 3] triangular face indices""" |
| utils3d.numpy.mesh.remove_corrupted_faces |
|
|
| @overload |
| def merge_duplicate_vertices(vertices: numpy_.ndarray, faces: numpy_.ndarray, tol: float = 1e-06) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Merge duplicate vertices of a triangular mesh. |
| Duplicate vertices are merged by selecte one of them, and the face indices are updated accordingly. |
| |
| ## Parameters |
| vertices (ndarray): [N, 3] 3-dimensional vertices |
| faces (ndarray): [T, 3] triangular face indices |
| tol (float, optional): tolerance for merging. Defaults to 1e-6. |
| |
| ## Returns |
| vertices (ndarray): [N_, 3] 3-dimensional vertices |
| faces (ndarray): [T, 3] triangular face indices""" |
| utils3d.numpy.mesh.merge_duplicate_vertices |
|
|
| @overload |
| def remove_unused_vertices(faces: numpy_.ndarray, *vertice_attrs, return_indices: bool = False) -> Tuple[numpy_.ndarray, ...]: |
| """Remove unreferenced vertices of a mesh. |
| Unreferenced vertices are removed, and the face indices are updated accordingly. |
| |
| ## Parameters |
| faces (ndarray): [T, P] face indices |
| *vertice_attrs: vertex attributes |
| |
| ## Returns |
| faces (ndarray): [T, P] face indices |
| *vertice_attrs: vertex attributes |
| indices (ndarray, optional): [N] indices of vertices that are kept. Defaults to None.""" |
| utils3d.numpy.mesh.remove_unused_vertices |
|
|
| @overload |
| def subdivide_mesh(vertices: numpy_.ndarray, faces: numpy_.ndarray, level: int = 1) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Subdivide a triangular mesh by splitting each triangle into 4 smaller triangles. |
| NOTE: All original vertices are kept, and new vertices are appended to the end of the vertex list. |
| |
| ## Parameters |
| vertices (ndarray): [N, 3] 3-dimensional vertices |
| faces (ndarray): [T, 3] triangular face indices |
| level (int, optional): level of subdivisions. Defaults to 1. |
| |
| ## Returns |
| vertices (ndarray): [N_, 3] subdivided 3-dimensional vertices |
| faces (ndarray): [(4 ** level) * T, 3] subdivided triangular face indices""" |
| utils3d.numpy.mesh.subdivide_mesh |
|
|
| @overload |
| def mesh_edges(faces: Union[numpy_.ndarray, Tuple[numpy_.ndarray, numpy_.ndarray], ForwardRef('csr_array')], return_face2edge: bool = False, return_edge2face: bool = False, return_counts: bool = False) -> Tuple[numpy_.ndarray, Union[numpy_.ndarray, ForwardRef('csr_array')], ForwardRef('csr_array'), ForwardRef('ndarray')]: |
| """Get undirected edges of a mesh. Optionally return additional mappings. |
| |
| ## Parameters |
| - `faces` (ndarray): polygon faces, which can be in 3 formats: |
| - Regular mesh in regular array: `(F, P)`, where each face has `P` vertices. |
| - Irregular mesh in segmented array: tuple of `(vertex_indices, offsets)`, where vertex_indices[offsets[i]:offsets[i+1]] are the vertex indices of face i. |
| - Irregular mesh in CSR array: `(F, V)` binary CSR array of indices, each row corresponds to the vertices of a face. |
| (Note that segmented array is almost equivalent to csr array: `vertex_indices` ~ `faces.indices`, `offsets` ~ `faces.indptr`.) |
| - `return_face2edge` (bool): whether to return the face to edge mapping |
| - `return_edge2face` (bool): whether to return the edge to face mapping |
| - `return_counts` (bool): whether to return the counts of edges |
| |
| ## Returns |
| - `edges` (ndarray): `(E, 2)` unique edges' vertex indices |
| |
| If `return_face2edge`, `return_edge2face`, `return_opposite_edge`, or `return_counts` is True, the corresponding outputs will be appended in order: |
| |
| - `face2edge` (ndarray | csr_array): mapping from faces to the indices of edges |
| - `(F, P)` if input `faces` is a dense array |
| - `(F, E)` if input `faces` is segmented array |
| - `edge2face` (csr_array): `(E, F)` binary sparse CSR matrix of edge to face. |
| - `counts` (ndarray): `(E,)` counts of each edge""" |
| utils3d.numpy.mesh.mesh_edges |
|
|
| @overload |
| def mesh_half_edges(faces: Union[numpy_.ndarray, Tuple[numpy_.ndarray, numpy_.ndarray], ForwardRef('csr_array')], return_face2edge: bool = False, return_edge2face: bool = False, return_twin: bool = False, return_next: bool = False, return_prev: bool = False, return_counts: bool = False) -> Tuple[numpy_.ndarray, Union[numpy_.ndarray, ForwardRef('csr_array')], ForwardRef('csr_array'), numpy_.ndarray, numpy_.ndarray, numpy_.ndarray, numpy_.ndarray]: |
| """Get half edges of a mesh. Optionally return additional mappings. |
| |
| ## Parameters |
| - `faces` (ndarray): polygon faces, which can be in 3 formats: |
| - `faces` (ndarray): polygon faces, which can be in 3 formats: |
| - Regular mesh in regular array: `(F, P)`, where each face has `P` vertices. |
| - Irregular mesh in segmented array: tuple of `(vertex_indices, offsets)`, where vertex_indices[offsets[i]:offsets[i+1]] are the vertex indices of face i. |
| - Irregular mesh in CSR array: `(F, V)` binary CSR array of indices, each row corresponds to the vertices of a face. |
| (Note that segmented array is almost equivalent to csr array: `vertex_indices` ~ `faces.indices`, `offsets` ~ `faces.indptr`.) |
| - `return_face2edge` (bool): whether to return the face to edge mapping |
| - `return_edge2face` (bool): whether to return the edge to face mapping |
| - `return_twin` (bool): whether to return the mapping from one edge to its opposite/twin edge |
| - `return_next` (bool): whether to return the mapping from one edge to its next edge in the face loop |
| - `return_prev` (bool): whether to return the mapping from one edge to its previous edge in the face loop |
| - `return_counts` (bool): whether to return the counts of edges |
| |
| ## Returns |
| - `edges` (ndarray): `(E, 2)` unique edges' vertex indices |
| |
| If `return_face2edge`, `return_edge2face`, `return_opposite_edge`, or `return_counts` is True, the corresponding outputs will be appended in order: |
| |
| - `face2edge` (ndarray | csr_array): mapping from faces to the indices of edges |
| - `(F, P)` if input `faces` is a dense array |
| - `(F, E)` if input `faces` is a sparse csr array |
| - `edge2face` (csr_array): `(E, F)` binary sparse CSR matrix of edge to face. |
| - `twin` (ndarray): `(E,)` mapping from edges to indices of opposite edges. -1 if not found. |
| - `next` (ndarray): `(E,)` mapping from edges to indices of next edges in the face loop. |
| - `prev` (ndarray): `(E,)` mapping from edges to indices of previous edges in the face loop. |
| - `counts` (ndarray): `(E,)` counts of each half edge |
| |
| NOTE: If the mesh is not manifold, `twin`, `next`, and `prev` can point to arbitrary one of the candidates.""" |
| utils3d.numpy.mesh.mesh_half_edges |
|
|
| @overload |
| def mesh_connected_components(faces: Union[numpy_.ndarray, Tuple[numpy_.ndarray, numpy_.ndarray], ForwardRef('csr_array'), NoneType] = None, num_vertices: Optional[int] = None) -> Union[numpy_.ndarray, Tuple[numpy_.ndarray, numpy_.ndarray]]: |
| """Compute connected faces of a mesh. |
| |
| ## Parameters |
| - `faces` (ndarray): polygon faces, which can be in 3 formats: |
| - Regular mesh in regular array: `(F, P)`, where each face has `P` vertices. |
| - Irregular mesh in segmented array: tuple of `(vertex_indices, offsets)`, where vertex_indices[offsets[i]:offsets[i+1]] are the vertex indices of face i. |
| - Irregular mesh in CSR array: `(F, V)` binary CSR array of indices, each row corresponds to the vertices of a face. |
| (Note that segmented array is almost equivalent to csr array: `vertex_indices` ~ `faces.indices`, `offsets` ~ `faces.indptr`.) |
| - `num_vertices` (int, optional): total number of vertices. If not given, only presented vertices in `faces` are considered. |
| |
| ## Returns |
| |
| If `num_vertices` is given, return: |
| - `labels` (ndarray): (N,) component labels of each vertex |
| |
| If `num_vertices` is None, return: |
| - `vertices_ids` (ndarray): (N,) vertex indices that are in the edges |
| - `labels` (ndarray): (N,) int32 component labels corresponding to `vertices_ids`""" |
| utils3d.numpy.mesh.mesh_connected_components |
|
|
| @overload |
| def graph_connected_components(edges: numpy_.ndarray, num_vertices: Optional[int] = None) -> Union[numpy_.ndarray, Tuple[numpy_.ndarray, numpy_.ndarray]]: |
| """Compute connected components of an undirected graph. |
| Using scipy.sparse.csgraph.connected_components as backend. |
| |
| ## Parameters |
| - `edges` (ndarray): (E, 2) edge indices |
| |
| ## Returns |
| |
| If `num_vertices` is given, return: |
| - `labels` (ndarray): (N,) component labels of each vertex |
| |
| If `num_vertices` is None, return: |
| - `vertices_ids` (ndarray): (N,) vertex indices that are in the edges |
| - `labels` (ndarray): (N,) int32 component labels corresponding to `vertices_ids`""" |
| utils3d.numpy.mesh.graph_connected_components |
|
|
| @overload |
| def mesh_adjacency_graph(adjacency: Literal['vertex2edge', 'vertex2face', 'edge2vertex', 'edge2face', 'face2edge', 'face2vertex', 'vertex2edge2vertex', 'vertex2face2vertex', 'edge2vertex2edge', 'edge2face2edge', 'face2edge2face', 'face2vertex2face'], faces: Union[numpy_.ndarray, Tuple[numpy_.ndarray, numpy_.ndarray], ForwardRef('csr_array'), NoneType] = None, edges: Optional[numpy_.ndarray] = None, num_vertices: Optional[int] = None, self_loop: bool = False) -> 'csr_array': |
| """Get adjacency graph of a mesh. |
| |
| ## Parameters |
| - `adjacency` (str): type of adjacency graph. Options: |
| - `'vertex2edge'`: vertex to adjacent edges. Returns (V, E) csr |
| - `'vertex2face'`: vertex to adjacent faces. Returns (V, F) csr |
| - `'edge2vertex'`: edge to adjacent vertices. Returns (E, V) csr |
| - `'edge2face'`: edge to its adjacent faces. Returns (E, F) csr |
| - `'face2edge'`: face to its adjacent edges. Returns (F, E) csr |
| - `'face2vertex'`: face to its adjacent vertices. Returns (F, V) csr |
| - `'vertex2edge2vertex'`: vertex to adjacent vertices if they share an edge. Returns (V, V) csr |
| - `'vertex2face2vertex'`: vertex to adjacent vertices if they share a face. Returns (V, V) csr |
| - `'edge2vertex2edge'`: edge to adjacent edges if they share a vertex. Returns (E, E) csr |
| - `'edge2face2edge'`: edge to adjacent edges if they share a face. Returns (E, E) csr |
| - `'face2edge2face'`: face to adjacent faces if they share an edge. Returns (F, F) csr |
| - `'face2vertex2face'`: face to adjacent faces if they share a vertex. Returns (F, F) csr |
| - `faces` (ndarray): polygon faces |
| - `(F, P)` dense array of indices, where each face has `P` vertices. |
| - `(F, V)` binary sparse csr array of indices, each row corresponds to the vertices of a face. |
| - `edges` (ndarray, optional): (E, 2) edge indices. NOTE: assumed to be undirected edges. |
| - `num_vertices` (int, optional): total number of vertices. |
| - `self_loop` (bool): whether to include self-loops in the adjacency graph. Defaults to False. |
| |
| ## Returns |
| - `graph` (csr_array): adjacency graph in csr format""" |
| utils3d.numpy.mesh.mesh_adjacency_graph |
|
|
| @overload |
| def flatten_mesh_indices(*args: numpy_.ndarray) -> Tuple[numpy_.ndarray, ...]: |
| utils3d.numpy.mesh.flatten_mesh_indices |
|
|
| @overload |
| def create_cube_mesh(tri: bool = False) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Create a cube mesh of size 1 centered at origin. |
| |
| ### Parameters |
| tri (bool, optional): return triangulated mesh. Defaults to False, which returns quad mesh. |
| |
| ### Returns |
| vertices (ndarray): shape (8, 3) |
| faces (ndarray): shape (12, 3)""" |
| utils3d.numpy.mesh.create_cube_mesh |
|
|
| @overload |
| def create_icosahedron_mesh(): |
| """Create an icosahedron mesh of centered at origin.""" |
| utils3d.numpy.mesh.create_icosahedron_mesh |
|
|
| @overload |
| def create_square_mesh(tri: bool = False) -> Tuple[numpy_.ndarray, numpy_.ndarray]: |
| """Create a square mesh of area 1 centered at origin in the xy-plane. |
| |
| ## Returns |
| vertices (ndarray): shape (4, 3) |
| faces (ndarray): shape (1, 4)""" |
| utils3d.numpy.mesh.create_square_mesh |
|
|
| @overload |
| def create_camera_frustum_mesh(extrinsics: numpy_.ndarray, intrinsics: numpy_.ndarray, depth: float = 1.0) -> Tuple[numpy_.ndarray, numpy_.ndarray, numpy_.ndarray]: |
| """Create a triangle mesh of camera frustum.""" |
| utils3d.numpy.mesh.create_camera_frustum_mesh |
|
|
| @overload |
| def merge_meshes(meshes: List[Tuple[numpy_.ndarray, ...]]) -> Tuple[numpy_.ndarray, ...]: |
| """Merge multiple meshes into one mesh. Vertices will be no longer shared. |
| |
| ## Parameters |
| - `meshes`: a list of tuple (faces, vertices_attr1, vertices_attr2, ....) |
| |
| ## Returns |
| - `faces`: [sum(T_i), P] merged face indices, contigous from 0 to sum(T_i) * P - 1 |
| - `*vertice_attrs`: [sum(T_i) * P, ...] merged vertex attributes, where every P values correspond to a face""" |
| utils3d.numpy.mesh.merge_meshes |
|
|
| @overload |
| def uv_map(*size: Union[int, Tuple[int, int]], top: float = 0.0, left: float = 0.0, bottom: float = 1.0, right: float = 1.0, dtype: numpy_.dtype = numpy_.float32) -> numpy_.ndarray: |
| """Get image UV space coordinate map, where (0., 0.) is the top-left corner of the image, and (1., 1.) is the bottom-right corner of the image. |
| This is commonly used as normalized image coordinates in texture mapping (when image is not flipped vertically). |
| |
| ## Parameters |
| - `*size`: `Tuple[int, int]` or two integers of map size `(height, width)` |
| - `top`: `float`, optional top boundary in uv space. Defaults to 0. |
| - `left`: `float`, optional left boundary in uv space. Defaults to 0. |
| - `bottom`: `float`, optional bottom boundary in uv space. Defaults to 1. |
| - `right`: `float`, optional right boundary in uv space. Defaults to 1. |
| - `dtype`: `np.dtype`, optional data type of the output uv map. Defaults to np.float32. |
| |
| ## Returns |
| - `uv (ndarray)`: shape `(height, width, 2)` |
| |
| ## Example Usage |
| |
| >>> uv_map(10, 10): |
| [[[0.05, 0.05], [0.15, 0.05], ..., [0.95, 0.05]], |
| [[0.05, 0.15], [0.15, 0.15], ..., [0.95, 0.15]], |
| ... ... ... |
| [[0.05, 0.95], [0.15, 0.95], ..., [0.95, 0.95]]]""" |
| utils3d.numpy.maps.uv_map |
|
|
| @overload |
| def pixel_coord_map(*size: Union[int, Tuple[int, int]], top: int = 0, left: int = 0, convention: Literal['integer-center', 'integer-corner'] = 'integer-center', dtype: numpy_.dtype = numpy_.float32) -> numpy_.ndarray: |
| """Get image pixel coordinates map, where (0, 0) is the top-left corner of the top-left pixel, and (width, height) is the bottom-right corner of the bottom-right pixel. |
| |
| ## Parameters |
| - `*size`: `Tuple[int, int]` or two integers of map size `(height, width)` |
| - `top`: `int`, optional top boundary of the pixel coord map. Defaults to 0. |
| - `left`: `int`, optional left boundary of the pixel coord map. Defaults to 0. |
| - `convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - `'integer-center'`: `pixel[i][j]` has integer coordinates `(j, i)` as its center, and occupies square area `[j - 0.5, j + 0.5) × [i - 0.5, i + 0.5)`. |
| The top-left corner of the top-left pixel is `(-0.5, -0.5)`, and the bottom-right corner of the bottom-right pixel is `(width - 0.5, height - 0.5)`. |
| - `'integer-corner'`: `pixel[i][j]` has coordinates `(j + 0.5, i + 0.5)` as its center, and occupies square area `[j, j + 1) × [i, i + 1)`. |
| The top-left corner of the top-left pixel is `(0, 0)`, and the bottom-right corner of the bottom-right pixel is `(width, height)`. |
| - `dtype`: `np.dtype`, optional data type of the output pixel coord map. Defaults to np.float32. |
| |
| ## Returns |
| ndarray: shape (height, width, 2) |
| |
| >>> pixel_coord_map(10, 10, convention='integer-center', dtype=int): |
| [[[0, 0], [1, 0], ..., [9, 0]], |
| [[0, 1], [1, 1], ..., [9, 1]], |
| ... ... ... |
| [[0, 9], [1, 9], ..., [9, 9]]] |
| |
| >>> pixel_coord_map(10, 10, convention='integer-corner', dtype=np.float32): |
| [[[0.5, 0.5], [1.5, 0.5], ..., [9.5, 0.5]], |
| [[0.5, 1.5], [1.5, 1.5], ..., [9.5, 1.5]], |
| ... ... ... |
| [[0.5, 9.5], [1.5, 9.5], ..., [9.5, 9.5]]]""" |
| utils3d.numpy.maps.pixel_coord_map |
|
|
| @overload |
| def screen_coord_map(*size: Union[int, Tuple[int, int]], top: float = 1.0, left: float = 0.0, bottom: float = 0.0, right: float = 1.0, dtype: numpy_.dtype = numpy_.float32) -> numpy_.ndarray: |
| """Get screen space coordinate map, where (0., 0.) is the bottom-left corner of the image, and (1., 1.) is the top-right corner of the image. |
| This is commonly used in graphics APIs like OpenGL. |
| |
| ## Parameters |
| - `*size`: `Tuple[int, int]` or two integers of map size `(height, width)` |
| - `top`: `float`, optional top boundary in the screen space. Defaults to 1. |
| - `left`: `float`, optional left boundary in the screen space. Defaults to 0. |
| - `bottom`: `float`, optional bottom boundary in the screen space. Defaults to 0. |
| - `right`: `float`, optional right boundary in the screen space. Defaults to 1. |
| - `dtype`: `np.dtype`, optional data type of the output map. Defaults to np.float32. |
| |
| ## Returns |
| (ndarray): shape (height, width, 2)""" |
| utils3d.numpy.maps.screen_coord_map |
|
|
| @overload |
| def build_grid_mesh(height: int, width: int, *, shared_vertices: bool = True) -> numpy_.ndarray: |
| """Get mesh of `height * width` faces arranged in a 2D grid. |
| |
| Parameters |
| ---- |
| height (int): height of the grid |
| width (int): width of the grid |
| shared_vertices (bool, optional): whether the vertices are shared among faces. Defaults to True. |
| |
| Returns |
| ---- |
| faces (ndarray): faces in shape (height, width, 4). |
| - If shared_vertices is `True`, the vertex indices are arranged from 0 to `(H + 1) * (W + 1) - 1` like |
| ``` |
| 0 ----------- 1 --- ... -------- W-1 --------------- W |
| | (0,0) | (0,1) | (0,W-1) | |
| W+1 ------- W+2 --- ... -------- 2*W --------------- 2*W+1 |
| | (1,0) | (1,1) | ... | |
| ... |
| | (H-1,0) | (H-1,1) | (H-1,W-1) | |
| H*(W+1) ----- H*(W+1)+1 --- ... --- (H+1)*(W+1)-2 ----- (H+1)*(W+1)-1 |
| ``` |
| - If shared_vertices is `False`, each face has its own 4 vertices. |
| The vertex indices are arranged from 0 to `H * W * 4 - 1`, like |
| ``` |
| 0 ------- 3 4 ------- 7 ... (W-1)*4 ---- (W-1)*4+3 |
| | (0,0) | | (0,1) | | (0,W-1) | |
| 1 ------- 2 5 ------- 6 ... (W-1)*4+1 -- (W-1)*4+2 |
| W*4 ----- W*4+3 |
| | (1,0) | .... |
| W*4+1 --- W*4+2 |
| ... |
| (H-1)*W*4 ---- (H-1)*W*4+3 ... H*W*4 - 4 ----- H*W*4 - 1 |
| | (H-1,0) | | (H-1,W-1) | |
| (H-1)*W*4+1 -- (H-1)*W*4+2 ... H*W*4 - 3 ------ H*W*4 - 2 |
| ```""" |
| utils3d.numpy.maps.build_grid_mesh |
|
|
| @overload |
| def build_mesh_from_map(*maps: numpy_.ndarray, mask: Optional[numpy_.ndarray] = None, domain: Literal['vertex', 'face'] = 'vertex', tri: bool = False) -> Tuple[numpy_.ndarray, ...]: |
| """Get a mesh regarding image pixel uv coordinates as vertices and image grid as faces. |
| |
| ## Parameters |
| *maps (ndarray): attribute maps in shape (height, width, [channels]) |
| mask (ndarray, optional): binary mask of shape (height, width), dtype=bool. Defaults to None. |
| domain (Literal['vertex', 'face'], optional): whether the pixel attributes correspond to vertices or faces. Defaults to 'vertex'. |
| tri (bool, optional): whether to triangulate the mesh. Defaults to False. |
| |
| ## Returns |
| faces (ndarray): faces connecting neighboring pixels. shape (T, 4) if tri is False, else (T, 3) |
| *attributes (ndarray): vertex or face attributes in corresponding order with input maps""" |
| utils3d.numpy.maps.build_mesh_from_map |
|
|
| @overload |
| def build_mesh_from_depth_map(depth: numpy_.ndarray, *maps: numpy_.ndarray, intrinsics: numpy_.ndarray, extrinsics: Optional[numpy_.ndarray] = None, atol: Optional[float] = None, rtol: Optional[float] = None, domain: Literal['vertex', 'face'] = 'vertex', tri: bool = False) -> Tuple[numpy_.ndarray, ...]: |
| """Get a mesh by lifting depth map to 3D, while removing depths of large depth difference. |
| |
| ## Parameters |
| depth (ndarray): [H, W] depth map |
| extrinsics (ndarray, optional): [4, 4] extrinsics matrix. Defaults to None. |
| intrinsics (ndarray, optional): [3, 3] intrinsics matrix. Defaults to None. |
| *maps (ndarray): [H, W, C] vertex attributes. Defaults to None. |
| atol (float, optional): absolute tolerance of difference. Defaults to None. |
| rtol (float, optional): relative tolerance of difference. Defaults to None. |
| triangles with vertices having depth difference larger than atol + rtol * depth will be marked. |
| domain (Literal['vertex', 'face'], optional): whether the pixel attributes correspond to vertices or faces. Defaults to 'vertex'. |
| tri (bool, optional): whether to triangulate the mesh. Defaults to False. |
| |
| ## Returns |
| faces (ndarray): [T, 3] faces |
| vertices (ndarray): [N, 3] vertices |
| *attributes (ndarray): [N, C] vertex attributes or [T, C] face attributes""" |
| utils3d.numpy.maps.build_mesh_from_depth_map |
|
|
| @overload |
| def depth_map_edge(depth: numpy_.ndarray, atol: Optional[float] = None, rtol: Optional[float] = None, ltol: Optional[float] = None, kernel_size: int = 3, mask: numpy_.ndarray = None) -> numpy_.ndarray: |
| """Compute the edge mask from depth map. The edge is defined as the pixels whose neighbors have large difference in depth. |
| |
| ## Parameters |
| depth (ndarray): shape (..., height, width), linear depth map |
| atol (float): absolute tolerance |
| rtol (float): relative tolerance |
| ltol (float): relative tolerance of inverse depth laplacian |
| |
| ## Returns |
| edge (ndarray): shape (..., height, width) of dtype torch.bool""" |
| utils3d.numpy.maps.depth_map_edge |
|
|
| @overload |
| def depth_map_aliasing(depth: numpy_.ndarray, atol: float = None, rtol: float = None, kernel_size: int = 3, mask: numpy_.ndarray = None) -> numpy_.ndarray: |
| """Compute the map that indicates the aliasing of x depth map, identifying pixels which neither close to the maximum nor the minimum of its neighbors. |
| ## Parameters |
| depth (ndarray): shape (..., height, width), linear depth map |
| atol (float): absolute tolerance |
| rtol (float): relative tolerance |
| |
| ## Returns |
| edge (ndarray): shape (..., height, width) of dtype torch.bool""" |
| utils3d.numpy.maps.depth_map_aliasing |
|
|
| @overload |
| def normal_map_edge(normals: numpy_.ndarray, tol: float, kernel_size: int = 3, mask: numpy_.ndarray = None) -> numpy_.ndarray: |
| """Compute the edge mask from normal map. |
| |
| ## Parameters |
| normal (ndarray): shape (..., height, width, 3), normal map |
| tol (float): tolerance in degrees |
| |
| ## Returns |
| edge (ndarray): shape (..., height, width) of dtype torch.bool""" |
| utils3d.numpy.maps.normal_map_edge |
|
|
| @overload |
| def point_map_to_normal_map(point: numpy_.ndarray, mask: numpy_.ndarray = None, edge_threshold: float = None) -> numpy_.ndarray: |
| """Calculate normal map from point map. Value range is [-1, 1]. |
| |
| ## Parameters |
| point (ndarray): shape (height, width, 3), point map |
| mask (optional, ndarray): shape (height, width), dtype=bool. Mask of valid depth pixels. Defaults to None. |
| edge_threshold (optional, float): threshold for the angle (in degrees) between the normal and the view direction. Defaults to None. |
| |
| ## Returns |
| normal (ndarray): shape (height, width, 3), normal map. """ |
| utils3d.numpy.maps.point_map_to_normal_map |
|
|
| @overload |
| def depth_map_to_point_map(depth: numpy_.ndarray, intrinsics: numpy_.ndarray, extrinsics: numpy_.ndarray = None) -> numpy_.ndarray: |
| """Unproject depth map to 3D points. |
| |
| ## Parameters |
| depth (ndarray): [..., H, W] depth value |
| intrinsics ( ndarray): [..., 3, 3] intrinsics matrix |
| extrinsics (optional, ndarray): [..., 4, 4] extrinsics matrix |
| |
| ## Returns |
| points (ndarray): [..., N, 3] 3d points""" |
| utils3d.numpy.maps.depth_map_to_point_map |
|
|
| @overload |
| def depth_map_to_normal_map(depth: numpy_.ndarray, intrinsics: numpy_.ndarray, mask: numpy_.ndarray = None, edge_threshold: float = None) -> numpy_.ndarray: |
| """Calculate normal map from depth map. Value range is [-1, 1]. Normal direction in OpenCV identity camera's coordinate system. |
| |
| ## Parameters |
| depth (ndarray): shape (height, width), linear depth map |
| intrinsics (ndarray): shape (3, 3), intrinsics matrix |
| mask (optional, ndarray): shape (height, width), dtype=bool. Mask of valid depth pixels. Defaults to None. |
| edge_threshold (optional, float): threshold for the angle (in degrees) between the normal and the view direction. Defaults to None. |
| |
| ## Returns |
| normal (ndarray): shape (height, width, 3), normal map. """ |
| utils3d.numpy.maps.depth_map_to_normal_map |
|
|
| @overload |
| def chessboard(*size: Union[int, Tuple[int, int]], grid_size: int, color_a: numpy_.ndarray, color_b: numpy_.ndarray) -> numpy_.ndarray: |
| """Get a chessboard image |
| |
| ## Parameters |
| - `*size`: `Tuple[int, int]` or two integers of map size `(height, width)` |
| - `grid_size (int)`: size of chessboard grid |
| - `color_a (ndarray)`: color of the grid at the top-left corner |
| - `color_b (ndarray)`: color in complementary grid cells |
| |
| ## Returns |
| image (ndarray): shape (height, width, channels), chessboard image""" |
| utils3d.numpy.maps.chessboard |
|
|
| @overload |
| def masked_nearest_resize(*image: numpy_.ndarray, mask: numpy_.ndarray, size: Tuple[int, int], return_index: bool = False) -> Tuple[Unpack[Tuple[numpy_.ndarray, ...]], numpy_.ndarray, Tuple[numpy_.ndarray, ...]]: |
| """Resize image(s) by nearest sampling with mask awareness. Suitable for sparse maps.  |
| - Downsampling: Assign the nearest valid pixel within the target pixel's receptive field. |
| - Upsampling: Assign the valid pixel to only the nearest pixel in the resized map. |
| |
| ### Parameters |
| - `*image`: Input image(s) of shape `(..., H, W, C)` or `(... , H, W)` |
| - You can pass multiple images to be resized at the same time for efficiency. |
| - `mask`: input mask of shape `(..., H, W)`, dtype=bool |
| - `size`: target size `(H', W')` |
| - `return_index`: whether to return the nearest neighbor indices in the original map for each pixel in the resized map. |
| Defaults to False. |
| |
| ### Returns |
| - `*resized_image`: resized image(s) of shape `(..., H', W', C)`. or `(..., H', W')` |
| - `resized_mask`: mask of the resized map of shape `(..., H', W')` |
| - `nearest_indices`: tuple of shape `(..., H', W')`. The nearest neighbor indices of the resized map of each dimension.""" |
| utils3d.numpy.maps.masked_nearest_resize |
|
|
| @overload |
| def masked_area_resize(*image: numpy_.ndarray, mask: numpy_.ndarray, size: Tuple[int, int]) -> Tuple[Unpack[Tuple[numpy_.ndarray, ...]], numpy_.ndarray]: |
| """Resize 2D map by area sampling with mask awareness. |
| |
| ### Parameters |
| - `*image`: Input image(s) of shape `(..., H, W, C)` or `(..., H, W)` |
| - You can pass multiple images to be resized at the same time for efficiency. |
| - `mask`: Input mask of shape `(..., H, W)` |
| - `size`: target image size `(H', W')` |
| |
| ### Returns |
| - `*resized_image`: resized image(s) of shape `(..., H', W', C)`. or `(..., H', W')` |
| - `resized_mask`: mask of the resized map of shape `(..., H', W')`""" |
| utils3d.numpy.maps.masked_area_resize |
|
|
| @overload |
| def colorize_depth_map(depth: numpy_.ndarray, mask: numpy_.ndarray = None, near: Optional[float] = None, far: Optional[float] = None, cmap: str = 'Spectral') -> numpy_.ndarray: |
| """Colorize depth map for visualization. |
| |
| ## Parameters |
| - `depth` (ndarray): shape (..., H, W), linear depth map |
| - `mask` (ndarray, optional): shape (..., H, W), dtype=bool. Mask of valid depth pixels. Defaults to None. |
| - `near` (float, optional): near plane for depth normalization. If None, use the 0.1% quantile of valid depth values. Defaults to None. |
| - `far` (float, optional): far plane for depth normalization. If None, use the 99.9% quantile of valid depth values. Defaults to None. |
| - `cmap` (str, optional): colormap name in matplotlib. Defaults to 'Spectral'. |
| |
| ## Returns |
| - `colored` (ndarray): shape (..., H, W, 3), dtype=uint8, RGB [0, 255]""" |
| utils3d.numpy.maps.colorize_depth_map |
|
|
| @overload |
| def colorize_normal_map(normal: numpy_.ndarray, mask: numpy_.ndarray = None, flip_yz: bool = False, normalize: bool = True) -> numpy_.ndarray: |
| """Colorize normal map for visualization. Value range is [-1, 1]. |
| |
| ## Parameters |
| - `normal` (ndarray): shape (H, W, 3), normal |
| - `mask` (ndarray, optional): shape (H, W), dtype=bool. Mask of valid depth pixels. Defaults to None. |
| - `flip_yz` (bool, optional): whether to flip the y and z. |
| - This is useful when converting between OpenCV and OpenGL camera coordinate systems. Defaults to False. |
| - `normalize` (bool, optional): whether to normalize the normal vectors. Defaults to True. |
| |
| ## Returns |
| - `colored` (ndarray): shape (H, W, 3), dtype=uint8, RGB in [0, 255]""" |
| utils3d.numpy.maps.colorize_normal_map |
|
|
| @overload |
| def colorize_segmentation_map(segmentation: numpy_.ndarray, mask: Optional[numpy_.ndarray] = None, vdim: int = 0) -> numpy_.ndarray: |
| """Colorize segmentation map for visualization. The same value will be assigned with the same color. |
| |
| Parameters |
| ---- |
| - `segmentation` (ndarray): shape (..., H, W, [...]), segmentation map. The last `ndim` dimensions are treated as value channels. |
| - `mask` (ndarray, optional): shape (..., H, W), binary mask indicating valid regions. Defaults to None (all regions are valid). |
| - `vdim` (int, optional): number of dimensions to treat as value channels. Defaults to 0 (scalars) |
| |
| Returns |
| ---- |
| - `colored` (ndarray): shape (..., H, W, 3), dtype=uint8, RGB in [0, 255]""" |
| utils3d.numpy.maps.colorize_segmentation_map |
|
|
| @overload |
| def colorize_probability_map(probability: numpy_.ndarray, mask: Optional[numpy_.ndarray] = None, cmap: str = 'viridis', alpha: float = 1.0, beta: float = 1.0): |
| """Colorize probability map for visualization. |
| |
| The remapping is: |
| `p' = p^alpha / (p^alpha + (1 - p)^beta)` |
| where larger `alpha` suppresses low-to-mid probabilities and larger `beta` suppresses high probabilities. |
| |
| Parameters |
| ------- |
| - `probability` (ndarray): shape (..., H, W), probability map with values in [0, 1]. |
| - `mask` (ndarray, optional): shape (..., H, W), binary mask indicating valid regions. Defaults to None (all regions are valid). |
| - `cmap` (str, optional): colormap name in matplotlib. Defaults to 'viridis'. |
| - `alpha` (float, optional): exponent applied to `probability` in contrast remapping. Defaults to 1.0. |
| - `beta` (float, optional): exponent applied to `(1 - probability)` in contrast remapping. Defaults to 1.0. |
| |
| Returns |
| ------ |
| - `colored` (ndarray): shape (..., H, W, 3), dtype=uint8, RGB in [0, 255]. |
| |
| Examples for tuning `alpha` and `beta` |
| ------ |
| |
| | Parameters | Curve shape | Effect | |
| |---|---|---| |
| | `alpha=2.5, beta=2.5` | Steep S-shape | Separate "possible" and "impossible" around 0.5 | |
| | `alpha=0.3, beta=1.0` | Fast early rise, then gradual flattening | Emphasize tiny probabilities near zero | |
| | `alpha=1.0, beta=0.3` | Flat early, then sharp rise near the end | Emphasize subtle differences near certainty (close to 1) | |
| | `alpha=0.5, beta=0.5` | Hourglass-like (inverse-S) | Increase contrast near both extremes globally |""" |
| utils3d.numpy.maps.colorize_probability_map |
|
|
| @overload |
| def flood_fill(*image: numpy_.ndarray, mask: numpy_.ndarray, return_index: bool = False) -> numpy_.ndarray: |
| """Flooding fill the holes in the image(s) according to the mask.  |
| |
| Parameters |
| ---- |
| - `*image` (ndarray): shape (..., height, width, [C]), input image(s) |
| - `mask` (ndarray): shape (..., height, width), binary mask indicating valid regions |
| |
| Returns |
| ---- |
| - `*filled_image` (ndarray): shape (..., height, width, [C]), flood filled map |
| - `filled_indices` (Tuple[ndarray, ...], optional): tuple of shape (..., height, width). The nearest neighbor indices of each pixel in the original map. |
| It satisfies `filled_image = image[filled_indices]`""" |
| utils3d.numpy.maps.flood_fill |
|
|
| @overload |
| def perlin_noise(x: numpy_.ndarray, seed: Optional[int] = None) -> numpy_.ndarray: |
| """Generate Perlin noise for the given coordinates. |
| |
| Parameters |
| ---- |
| - `x` (ndarray): shape (*batch_shape, N_1, ..., N_D, D), coordinates to sample Perlin. |
| If input ndim is more than D + 1, the leading dimensions are treated as batch dimensions. Instances in the batch have different noise patterns. |
| - `seed` (int, optional): random seed. The same seed will generate the same noise pattern(s). Defaults to None. |
| |
| Returns |
| ---- |
| - `y` (ndarray): shape (*batch_shape, N_1, ..., N_D), Perlin noise value at the given coordinates and seed. Value range is approximately [-1, 1]""" |
| utils3d.numpy.maps.perlin_noise |
|
|
| @overload |
| def perlin_noise_map(size: Tuple[int, ...], frequency: Union[float, numpy_.ndarray], seed: Optional[int] = None, dtype: Optional[numpy_.dtype] = numpy_.float32) -> numpy_.ndarray: |
| """Generate Perlin noise map. |
| |
| Parameters |
| ---- |
| - `size` (Tuple[int, ...]): size of the noise map (..., H, W) |
| - `frequency` (float | ndarray): frequency relative to map's larger dimension max(H, W) of the Perlin noise. |
| Represents how many periods of noise fit in the larger dimension of the map. |
| - `seed` (int, optional): random seed. The same seed will generate the same noise pattern(s). Defaults to None. |
| |
| Returns |
| ---- |
| - `noise_map` (ndarray): shape (..., H, W), Perlin noise map. Value range is approximately [-1, 1]""" |
| utils3d.numpy.maps.perlin_noise_map |
|
|
| @overload |
| def fractal_perlin_noise_map(size: Tuple[int, ...], base_frequency: Union[float, numpy_.ndarray], octaves: int = 4, lacunarity: float = 2.0, gain: float = 0.5, seed: Optional[int] = None, dtype: Optional[numpy_.dtype] = numpy_.float32) -> numpy_.ndarray: |
| """Generate fractal Perlin noise map.  |
| |
| Parameters |
| ---- |
| - `size` (Tuple[int, ...]): size of the noise map (..., H, W) |
| - `base_frequency` (float | ndarray): base frequency (relative to map's larger dimension max(H, W)) of the Perlin noise. |
| Represents how many periods of noise fit in the larger dimension of the map. |
| - `octaves` (int, optional): number of octaves. Defaults to 4. |
| - `lacunarity` (float, optional): frequency multiplier between octaves. Defaults to 2.0. |
| - `gain` (float, optional): amplitude multiplier between octaves. Defaults to 0.5. |
| - `seed` (int, optional): random seed. The same seed will generate the same noise pattern. Defaults to None. |
| |
| Returns |
| ---- |
| - `noise_map` (ndarray): shape (..., H, W), fractal Perlin noise map. Value range is approximately [-1, 1]""" |
| utils3d.numpy.maps.fractal_perlin_noise_map |
|
|
| @overload |
| def RastContext(*args, **kwargs): |
| """Context for numpy-side rasterization. Based on moderngl. |
| """ |
| utils3d.numpy.rasterization.RastContext |
|
|
| @overload |
| def rasterize_triangles(size: Tuple[int, int], *, vertices: numpy_.ndarray, attributes: Optional[numpy_.ndarray] = None, attributes_domain: Optional[Literal['vertex', 'face']] = 'vertex', faces: Optional[numpy_.ndarray] = None, view: numpy_.ndarray = None, projection: numpy_.ndarray = None, extrinsics: numpy_.ndarray = None, intrinsics: numpy_.ndarray = None, near: float = 0.01, far: float = inf, cull_backface: bool = False, return_depth: bool = False, return_interpolation: bool = False, background: Optional[Dict[str, numpy_.ndarray]] = None, ctx: Optional[utils3d.numpy.rasterization.RastContext] = None) -> Dict[str, numpy_.ndarray]: |
| """Rasterize triangles. |
| |
| Parameters |
| ---- |
| - `size` (Tuple[int, int]): (height, width) of the output image |
| - `vertices` (ndarray): (N, 3) or (T, 3, 3) |
| - `faces` (Optional[ndarray]): (T, 3) or None. If `None`, the vertices must be an array with shape (T, 3, 3) |
| - `attributes` (ndarray): (N, C), (T, 3, C) for vertex domain or (T, C) for face domain |
| - `attributes_domain` (Literal['vertex', 'face']): domain of the attributes |
| - `view` | `extrinsics` (ndarray): (4, 4) View matrix or extrinsics matrix. Provide either one of them. |
| - `projection` | `intrinsics` (ndarray): (4, 4) Projection matrix or (3, 3) Intrinsics matrix. Provide either one of them. |
| - `cull_backface` (bool): whether to cull backface |
| - `background` (Optional[Dict[str, ndarray]]): background to composite with. Contains the same keys as the return dictionary, each with shape matching the output. |
| - `ctx` (RastContext): rasterization context. Created by `RastContext()`. Default to the thread-local default context. |
| |
| Returns |
| ---- |
| A dictionary containing |
| |
| - `mask` (ndarray): (H, W) bool mask of valid pixels |
| |
| if attributes is not None |
| - `image` (ndarray): (H, W, C) float32 rendered image corresponding to the input attributes |
| |
| if return_depth is True |
| - `depth` (ndarray): (H, W) float32 camera space linear depth. Empty pixels are filled with inf. |
| |
| if return_interpolation is True |
| - `interpolation_id` (ndarray): (H, W) int32 triangle ID map |
| - `interpolation_uv` (ndarray): (H, W, 2) float32 triangle UV (first two channels of barycentric coordinates)""" |
| utils3d.numpy.rasterization.rasterize_triangles |
|
|
| @overload |
| def rasterize_triangles_peeling(size: Tuple[int, int], *, vertices: numpy_.ndarray, attributes: numpy_.ndarray, attributes_domain: Literal['vertex', 'face'] = 'vertex', faces: Optional[numpy_.ndarray] = None, view: numpy_.ndarray = None, projection: numpy_.ndarray = None, extrinsics: numpy_.ndarray = None, intrinsics: numpy_.ndarray = None, near: float = 0.01, far: float = inf, cull_backface: bool = False, return_depth: bool = False, return_interpolation: bool = False, ctx: Optional[utils3d.numpy.rasterization.RastContext] = None) -> Iterator[Iterator[Dict[str, numpy_.ndarray]]]: |
| """Rasterize triangles with depth peeling. |
| |
| Parameters |
| ---- |
| - `size` (Tuple[int, int]): (height, width) of the output image |
| - `vertices` (ndarray): (N, 3) or (T, 3, 3) |
| - `faces` (Optional[ndarray]): (T, 3) or None. If `None`, the vertices must be an array with shape (T, 3, 3) |
| - `attributes` (ndarray): (N, C), (T, 3, C) for vertex domain or (T, C) for face domain |
| - `attributes_domain` (Literal['vertex', 'face']): domain of the attributes |
| - `view` | `extrinsics` (ndarray): (4, 4) View matrix or extrinsics matrix. Provide either one of them. |
| - `projection` | `intrinsics` (ndarray): (4, 4) Projection matrix or (3, 3) Intrinsics matrix. Provide either one of them. |
| - `near` (float): near clipping plane. Only used for intrinsics. Ignored if projection matrix is provided. |
| - `far` (float): far clipping plane. Only used for intrinsics. Ignored if projection matrix is provided. |
| - `cull_backface` (bool): whether to cull backfaces |
| - `ctx` (RastContext): rasterization context. Created by `RastContext()`. Default to the thread-local default context. |
| |
| Returns |
| ---- |
| A generator that yields dictionaries for each peeling layer containing: |
| |
| - `mask` (ndarray): (H, W) bool mask of valid pixels in this layer |
| |
| if attributes is not None |
| - `image` (ndarray): (H, W, C) float32 rendered image corresponding to the input attributes |
| |
| if return_depth is True |
| - `depth` (ndarray): (H, W) float32 camera space linear depth. Empty pixels are filled with inf. |
| |
| if return_interpolation is True |
| - `interpolation_id` (ndarray): (H, W) int32 triangle ID map |
| - `interpolation_uv` (ndarray): (H, W, 2) float32 triangle UV (first two channels of barycentric coordinates) |
| |
| The last layer yielded will be empty (no pixels covered), then the generator stops. |
| |
| Example |
| ---- |
| ``` |
| for i, layer_output in enumerate(rasterize_triangles_peeling( |
| (512, 512), |
| vertices=vertices, |
| faces=faces, |
| attributes=attributes, |
| view=view, |
| projection=projection |
| )): |
| print(f"Layer {i}:") |
| for key, value in layer_output.items(): |
| print(f" {key}: {value.shape}") |
| if i >= 4: # Stop after 5 layers at most |
| break |
| ```""" |
| utils3d.numpy.rasterization.rasterize_triangles_peeling |
|
|
| @overload |
| def rasterize_lines(size: Tuple[int, int], *, vertices: numpy_.ndarray, attributes: Optional[numpy_.ndarray], attributes_domain: Literal['vertex', 'line'] = 'vertex', lines: numpy_.ndarray | None = None, view: Optional[numpy_.ndarray] = None, projection: Optional[numpy_.ndarray] = None, extrinsics: Optional[numpy_.ndarray] = None, intrinsics: Optional[numpy_.ndarray] = None, near: float = 0.01, far: float = inf, line_width: float = 1.0, return_depth: bool = False, return_interpolation: bool = False, background: Optional[Dict[str, numpy_.ndarray]] = None, ctx: Optional[utils3d.numpy.rasterization.RastContext] = None) -> Tuple[numpy_.ndarray, ...]: |
| """Rasterize lines. |
| |
| Parameters |
| ---- |
| - `size` (Tuple[int, int]): (height, width) of the output image |
| - `vertices` (ndarray): (N, 3) or (L, 2, 3) |
| - `attributes` (ndarray): (N, C), (T, 3, C) for vertex domain or (T, C) for face domain |
| - `attributes_domain` (Literal['vertex', 'face']): domain of the attributes |
| - `lines` (ndarray): (L, 2) int32 array of line vertex indices. If None, vertices shape must be (L, 2, 3) and will be interpreted as line segments directly. |
| - `view` | `extrinsics` (ndarray): (4, 4) View matrix or extrinsics matrix. Provide either one of them. |
| - `projection` | `intrinsics` (ndarray): (4, 4) Projection matrix or (3, 3) Intrinsics matrix. Provide either one of them. |
| - `near` (float): near clipping plane. Only used for intrinsics. Ignored if projection matrix is provided. |
| - `far` (float): far clipping plane. Only used for intrinsics. Ignored if projection matrix is provided. |
| - `background` (Optional[Dict[str, ndarray]]): background to composite with. Contains the same keys as the return dictionary, each with shape matching the output. |
| - `ctx` (RastContext): rasterization context. Created by `RastContext()`. Defaults to the current default context. |
| |
| Returns |
| ---- |
| A dictionary containing |
| |
| - `mask` (ndarray): (H, W) bool mask of valid pixels |
| |
| if attributes is not None |
| - `image` (ndarray): (H, W, C) float32 rendered image corresponding to the input attributes |
| |
| if return_depth is True |
| - `depth` (ndarray): (H, W) float32 camera space linear depth, ranging from 0 to 1. |
| |
| if return_interpolation is True |
| - `interpolation_id` (ndarray): (H, W) int32 triangle ID map |
| - `interpolation_uv` (ndarray): (H, W, 2) float32 triangle UV (first two channels of barycentric coordinates)""" |
| utils3d.numpy.rasterization.rasterize_lines |
|
|
| @overload |
| def rasterize_point_cloud(size: Tuple[int, int], *, points: numpy_.ndarray, point_sizes: Union[float, numpy_.ndarray] = 10, point_size_in: Literal['2d', '3d'] = '2d', point_shape: Literal['triangle', 'square', 'pentagon', 'hexagon', 'circle'] = 'square', attributes: Optional[numpy_.ndarray] = None, view: numpy_.ndarray = None, projection: numpy_.ndarray = None, extrinsics: numpy_.ndarray = None, intrinsics: numpy_.ndarray = None, near: float = 0.01, far: float = inf, return_depth: bool = False, return_point_id: bool = False, background: Optional[Dict[str, numpy_.ndarray]] = None, ctx: Optional[utils3d.numpy.rasterization.RastContext] = None) -> Dict[str, numpy_.ndarray]: |
| """Rasterize point cloud. |
| |
| Parameters |
| ---- |
| - `size` (Tuple[int, int]): (height, width) of the output image |
| - `points` (ndarray): (N, 3) |
| - `point_sizes` (ndarray): (N,) or float |
| - `point_size_in`: Literal['2d', '3d'] = '2d'. Whether the point sizes are in 2D (size in pixels) or 3D (size in world units). |
| - `point_shape`: Literal['triangle', 'square', 'pentagon', 'hexagon', 'circle'] = 'square'. The visual shape of the points. |
| - `attributes` (ndarray): (N, C) |
| - `view` | `extrinsics` (ndarray): (4, 4) View matrix or extrinsics matrix. Provide either one of them. |
| - `projection` | `intrinsics` (ndarray): (4, 4) Projection matrix or (3, 3) Intrinsics matrix. Provide either one of them. |
| - `near` (float): near clipping plane. Only used for intrinsics. Ignored if projection matrix is provided. |
| - `far` (float): far clipping plane. Only used for intrinsics. Ignored if projection matrix is provided. |
| - `return_depth` (bool): whether to return depth map |
| - `return_point_id` (bool): whether to return point ID map |
| - `background` (Optional[Dict[str, ndarray]]): background to composite with. Contains the same keys as the return dictionary, each with shape matching the output. |
| - `ctx` (RastContext): rasterization context. Created by `RastContext()`. Defaults to the current default context. |
| |
| Returns |
| ---- |
| A dictionary containing |
| |
| if attributes is not None |
| - `image` (ndarray): (H, W, C) float32 rendered image corresponding to the input attributes |
| |
| if return_depth is True |
| - `depth` (ndarray): (H, W) float32 camera space linear depth, ranging from 0 to 1. |
| |
| if return_point_id is True |
| - `point_id` (ndarray): (H, W) int32 point ID map""" |
| utils3d.numpy.rasterization.rasterize_point_cloud |
|
|
| @overload |
| def sample_texture(uv_map: numpy_.ndarray, texture_map: numpy_.ndarray, interpolation: Literal['linear', 'nearest'] = 'linear', mipmap_level: Union[int, Tuple[int, int]] = 0, repeat: Union[bool, Tuple[bool, bool]] = False, anisotropic: float = 1.0, ctx: Optional[utils3d.numpy.rasterization.RastContext] = None) -> numpy_.ndarray: |
| """Sample from a texture map with a UV map.""" |
| utils3d.numpy.rasterization.sample_texture |
|
|
| @overload |
| def test_rasterization(ctx: Optional[utils3d.numpy.rasterization.RastContext] = None): |
| """Test if rasterization works. It will render a cube with random colors and save it as a CHECKME.png file.""" |
| utils3d.numpy.rasterization.test_rasterization |
|
|
| @overload |
| def read_extrinsics_from_colmap(file: Union[str, pathlib._local.Path]) -> Union[numpy_.ndarray, List[int], List[str]]: |
| """Read extrinsics from colmap `images.txt` file. |
| ## Parameters |
| file: Path to `images.txt` file. |
| ## Returns |
| extrinsics: (N, 4, 4) array of extrinsics. |
| camera_ids: List of int, camera ids. Length is N. Note that camera ids in colmap typically starts from 1. |
| image_names: List of str, image names. Length is N.""" |
| utils3d.numpy.io.colmap.read_extrinsics_from_colmap |
|
|
| @overload |
| def read_intrinsics_from_colmap(file: Union[str, pathlib._local.Path], normalize: bool = False) -> Tuple[List[int], numpy_.ndarray, numpy_.ndarray]: |
| """Read intrinsics from colmap `cameras.txt` file. |
| ## Parameters |
| file: Path to `cameras.txt` file. |
| normalize: Whether to normalize the intrinsics. If True, the intrinsics will be normalized. (mapping coordinates to [0, 1] range) |
| ## Returns |
| camera_ids: List of int, camera ids. Length is N. Note that camera ids in colmap typically starts from 1. |
| intrinsics: (N, 3, 3) array of intrinsics. |
| distortions: (N, 5) array of distortions.""" |
| utils3d.numpy.io.colmap.read_intrinsics_from_colmap |
|
|
| @overload |
| def write_extrinsics_as_colmap(file: Union[str, pathlib._local.Path], extrinsics: numpy_.ndarray, image_names: Union[str, List[str]] = 'image_{i:04d}.png', camera_ids: List[int] = None): |
| """Write extrinsics to colmap `images.txt` file. |
| ## Parameters |
| file: Path to `images.txt` file. |
| extrinsics: (N, 4, 4) array of extrinsics. |
| image_names: str or List of str, image names. Length is N. |
| If str, it should be a format string with `i` as the index. (i starts from 1, in correspondence with IMAGE_ID in colmap) |
| camera_ids: List of int, camera ids. Length is N. |
| If None, it will be set to [1, 2, ..., N].""" |
| utils3d.numpy.io.colmap.write_extrinsics_as_colmap |
|
|
| @overload |
| def write_intrinsics_as_colmap(file: Union[str, pathlib._local.Path], intrinsics: numpy_.ndarray, width: int, height: int, normalized: bool = False): |
| """Write intrinsics to colmap `cameras.txt` file. Currently only support PINHOLE model (no distortion) |
| ## Parameters |
| file: Path to `cameras.txt` file. |
| intrinsics: (N, 3, 3) array of intrinsics. |
| width: Image width. |
| height: Image height. |
| normalized: Whether the intrinsics are normalized. If True, the intrinsics will unnormalized for writing.""" |
| utils3d.numpy.io.colmap.write_intrinsics_as_colmap |
|
|
| @overload |
| def read_obj(file: Union[str, pathlib._local.Path, _io.TextIOWrapper], encoding: Optional[str] = None, ignore_unknown: bool = False) -> utils3d.numpy.io.obj.WavefrontOBJDict: |
| """Read wavefront .obj file. |
| |
| Parameters |
| ---- |
| - `file` (str, Path, TextIOWrapper): filepath or file object |
| - `encoding` (str, optional): file encoding |
| - `ignore_unknown` (bool): whether to ignore unknown keywords in .obj file. Default to False. |
| |
| Returns |
| ---- |
| A dictionary maybe containing the following fields. Note that some fields may be absent if not present in the .obj file: |
| |
| Vertices and attributes data: |
| - `v` (ndarray): (N_v, 3 or 4) vertex coordinates. |
| - `vt` (ndarray): (N_vt, 2 or 3). vertex texture coordinates. |
| - `vn` (ndarray): (N_vn, 3). vertex normals. |
| |
| Primitive definitions (face/line). NOTE: all indices are 0-based, unlike the 1-based indexing in .obj file. |
| - `f` (ndarray): Vertex indices in each face. |
| - If all faces have the same number of vertices: (M, K) |
| - If faces have different numbers of vertices: a tuple of segmented array: |
| - `data` (ndarray): flattened array of shape (sum(K_i),) |
| - `offsets` (ndarray): shape (M + 1,), offsets of each face in the flattened array |
| - `ft` (ndarray): Vertex texture coordinate indices of each face. The same format as `f`. |
| - `fn` (ndarray): Vertex normal indices of each face. The same format as `f`. |
| - `l` (ndarray): Vertex indices of each line segment. |
| - If all lines have the same number of vertices: (L, K_line) |
| - If lines have different numbers of vertices: a tuple of segmented array: |
| - `data` (ndarray): flattened array of shape (sum(K_line_i),) |
| - `offsets` (ndarray): shape (L + 1,), offsets of each line in the flattened array |
| - `lt` (ndarray): Vertex texture coordinate indices of each line. The same format as `l`. |
| - `p` (ndarray): Vertex indices of each point. 1D array of shape (N_p,) |
| - `pt` (ndarray): Vertex texture coordinate indices of each point. The same format as `p`. |
| |
| Object/Group/Material info: |
| - `o` (Dict[str, Dict[Literal['f', 'l', 'p'], slice]]). The objects and their corresponding faces/lines/points. E.g. `o['object_A']['f']` gives the slice of faces belonging to object_A. |
| - `g` (Dict[str, Dict[Literal['f', 'l', 'p'], slice]]). The groups and their corresponding faces/lines/points. E.g. `g['group_A']['f']` gives the slice of faces belonging to group_A. |
| - `usemtl` (Dict[str, Dict[Literal['f', 'l', 'p'], slice]]). The materials and their corresponding faces/lines/points. E.g. `usemtl['material_A']['f']` gives the slice of faces using material_A. |
| |
| Here, `names` is a list of names, and `offsets` is an array of shape (num_entities + 1,) indicating the start and end indices of faces belonging to each object/group/material. |
| For example, the second material has name `material_names[1]`, and its faces are `f[material_offsets[1]:material_offsets[2]]`. |
| |
| Material library: |
| - `mtllib` (List[str]): list of material library filenames - `mtllib` lines in .obj file.""" |
| utils3d.numpy.io.obj.read_obj |
|
|
| @overload |
| def write_obj(file: Union[str, pathlib._local.Path, os.PathLike], obj: utils3d.numpy.io.obj.WavefrontOBJDict, encoding: Optional[str] = None): |
| utils3d.numpy.io.obj.write_obj |
|
|
| @overload |
| def read_ply(file: Union[str, os.PathLike, IO]) -> Dict[str, Dict[str, Union[numpy_.ndarray, Tuple[numpy_.ndarray, numpy_.ndarray]]]]: |
| """Read a PLY file. Supports arbitrary properties, polygonal meshes. Very fast. |
| |
| Parameters |
| ---------- |
| - `file` (str | os.PathLike | IO): Path to the PLY file or a file-like object. |
| |
| Returns |
| ------- |
| - `data` (Dict): Parsed PLY data. Example |
| ```python |
| { |
| "vertex": { |
| "x": ndarray, |
| "y": ndarray, |
| "z": ndarray, |
| ... # other properties, like "nx", "ny", "nz", "red", "green", "blue", etc. |
| }, |
| "face": { |
| "vertex_indices": ndarray for regular lists or (ndarray, offsets ndarray) for irregular lists, |
| ... |
| }, |
| ... |
| } |
| ``` |
| |
| Performance |
| ------- |
| |
| Tested on a few binary PLY files: |
| |
| | Content Type | `utils3d` | `Open3D` | `Trimesh` | `plyfile` | `meshio` | |
| |----------- |------------| -------- |-----------|-----------| ---------| |
| | Point Cloud (V=921,600) | 26.3 ms | 132.8 ms | 36.8 ms | 23.1 ms | 25.8 ms | |
| | Triangle Mesh (V=425,949, F=841,148) | 17.4 ms | 144.8 ms | 341.9 ms | 2655.5 ms | 366.8 ms | |
| | Polygon Mesh (V=437,645, F=871,414) | 289.5 ms | x | x | 1999.5 ms | 3905.3 ms |""" |
| utils3d.numpy.io.ply.read_ply |
|
|
| @overload |
| def write_ply(file: Union[str, os.PathLike, IO], data: Dict[str, Dict[str, Union[numpy_.ndarray, Tuple[numpy_.ndarray, numpy_.ndarray]]]], format_: Literal['ascii', 'binary_little_endian', 'binary_big_endian'] = 'binary_little_endian') -> None: |
| """Write a PLY file. Supports arbitrary properties, polygonal meshes. |
| |
| Parameters |
| ---------- |
| - `file` (str | os.PathLike | IO): Path to the PLY file or a file-like object. |
| - `data` (Dict): PLY data to write. The structure is like |
| ```python |
| { |
| "vertex": { |
| "x": ndarray, |
| "y": ndarray, |
| "z": ndarray, |
| ... # other properties, like "nx", "ny", "nz", "red", "green", "blue", etc. |
| }, |
| "face": { |
| "vertex_indices": ndarray for regular lists or (ndarray, offsets ndarray) for irregular lists, |
| ... |
| }, |
| ... |
| } |
| ``` |
| - `format` (str): PLY format. Options are 'ascii', 'binary_little_endian', 'binary_big_endian'. |
| |
| Performance |
| ------- |
| |
| | Content Type | `utils3d` | `Open3D` | `Trimesh` | `plyfile` | `meshio` | |
| |----------- |------------| -------- |-----------|-----------|---------| |
| | Point Cloud (V=921,600)| 45.1 ms | 175.1 ms | 47.7 ms | 9.2 ms | 43.9 ms | |
| | Triangle Mesh (V=425,949, F=841,148) | 38.3 ms | 137.9 ms | 41.3 ms | 2063.1 ms | 46.9 ms | |
| | Polygon Mesh (V=437,645, F=871,414) | 234.0 ms | x | x | 1653.2 ms | 12360.8 ms |""" |
| utils3d.numpy.io.ply.write_ply |
|
|
| @overload |
| def sliding_window(x: torch_.Tensor, window_size: Union[int, Tuple[int, ...]], stride: Union[int, Tuple[int, ...], NoneType] = None, dilation: Union[int, Tuple[int, ...], NoneType] = None, pad_size: Union[int, Tuple[int, int], Tuple[Tuple[int, int]], NoneType] = None, pad_mode: str = 'constant', pad_value: numbers.Number = 0, dim: Tuple[int, ...] = None) -> torch_.Tensor: |
| """Get a sliding window of the input array. |
| This function is a wrapper of `torch.nn.functional.unfold` with additional support for padding and stride. |
| |
| ## Parameters |
| - `x` (Tensor): Input tensor. |
| - `window_size` (int or Tuple[int,...]): Size of the sliding window. If int |
| is provided, the same size is used for all specified axes. |
| - `stride` (Optional[Tuple[int,...]]): Stride between the sliding windows. If None, |
| no stride is applied. If int is provided, the same stride is used for all specified axes. |
| - `dilation` (Optional[Tuple[int,...]]): Dilation in each sliding window. If None, |
| no dilation is applied. If int is provided, the same dilation is used for all specified axes. |
| - `pad_size` (Optional[Union[int, Tuple[int, int], Tuple[Tuple[int, int]]]]): Size of padding to apply before sliding window. |
| Corresponding to `axis`. |
| - General format is `((before_1, after_1), (before_2, after_2), ...)`. |
| - Shortcut formats: |
| - `int` -> same padding before and after for all axes; |
| - `(int, int)` -> same padding before and after for each axis; |
| - `((int,), (int,) ...)` -> specify padding for each axis, same before and after. |
| - `pad_mode` (str): Padding mode to use. Refer to `numpy.pad` for more details. |
| - `pad_value` (Union[int, float]): Value to use for constant padding. Only used |
| when `pad_mode` is 'constant'. |
| - `axis` (Optional[Tuple[int,...]]): Axes to apply the sliding window. If None, all axes are used. |
| |
| ## Returns |
| - (Tensor): Sliding window of the input array. |
| - If no padding, the output is a view of the input array with zero copy. |
| - Otherwise, the output is no longer a view but a copy of the padded array.""" |
| utils3d.torch.utils.sliding_window |
|
|
| @overload |
| def masked_min(input: torch_.Tensor, mask: torch_.BoolTensor, dim: int = None, keepdim: bool = False) -> Union[torch_.Tensor, Tuple[torch_.Tensor, torch_.Tensor]]: |
| """Similar to torch.min, but with mask |
| """ |
| utils3d.torch.utils.masked_min |
|
|
| @overload |
| def masked_max(input: torch_.Tensor, mask: torch_.BoolTensor, dim: int = None, keepdim: bool = False) -> Union[torch_.Tensor, Tuple[torch_.Tensor, torch_.Tensor]]: |
| """Similar to torch.max, but with mask |
| """ |
| utils3d.torch.utils.masked_max |
|
|
| @overload |
| def lookup(key: torch_.Tensor, query: torch_.Tensor) -> torch_.LongTensor: |
| """Look up `query` in `key` like a dictionary. Useful for COO indexing. |
| |
| Parameters |
| ---- |
| - `key` (Tensor): shape `(K, *key_shape)`, the array to search in |
| - `query` (Tensor): shape `(..., *key_shape)`, the array to search for. `...` represents any number of batch dimensions. |
| |
| Returns |
| ---- |
| - `indices` (Tensor): shape `(...,)` shape `(...,)` indices in `key` for each `query`. If a query is not found in key, the corresponding index will be -1. |
| |
| Notes |
| ---- |
| - If using pytorch implementation (based on `torch.unique`), the complexity is `O((Q + K) * log(Q + K))` where `Q` is the number of queries and `K` is the number of keys. |
| - If using triton implementation (based on hashmap), the average complexity `O(Q + K)`. Much faster for large `Q` and `K`.""" |
| utils3d.torch.utils.lookup |
|
|
| @overload |
| def lookup_get(key: torch_.Tensor, value: torch_.Tensor, get_key: torch_.Tensor, default_value: Union[numbers.Number, torch_.Tensor] = 0) -> torch_.Tensor: |
| """Dictionary-like get for arrays |
| |
| ## Parameters |
| - `key` (Tensor): shape `(N, *key_shape)`, the key array of the dictionary to get from |
| - `value` (Tensor): shape `(N, *value_shape)`, the value array of the dictionary to get from |
| - `get_key` (Tensor): shape `(M, *key_shape)`, the key array to get for |
| - `default_value` (Union[Number, Tensor]): value to return if a key in `get_key` is not found in `key`. A scalar or tensor broadcastable to shape `(..., *value_shape)` |
| |
| ## Returns |
| `get_value` (Tensor): shape `(M, *value_shape)`, result values corresponding to `get_key`""" |
| utils3d.torch.utils.lookup_get |
|
|
| @overload |
| def lookup_set(key: torch_.Tensor, value: torch_.Tensor, set_key: torch_.Tensor, set_value: torch_.Tensor, append: bool = False, inplace: bool = False) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Dictionary-like set for arrays. |
| |
| ## Parameters |
| - `key` (Tensor): shape `(N, *key_shape)`, the key array of the dictionary to set |
| - `value` (Tensor): shape `(N, *value_shape)`, the value array of the dictionary to set |
| - `set_key` (Tensor): shape `(M, *key_shape)`, the key array to set for |
| - `set_value` (Tensor): shape `(M, *value_shape)`, the value array to set as |
| - `append` (bool): If True, append the (key, value) pairs in (set_key, set_value) that are not in (key, value) to the result. |
| - `inplace` (bool): If True, modify the input `value` array |
| |
| ## Returns |
| - `result_key` (Tensor): shape `(N_new, *value_shape)`. N_new = N + number of new keys added if append is True, else N. |
| - `result_value (Tensor): shape `(N_new, *value_shape)` """ |
| utils3d.torch.utils.lookup_set |
|
|
| @overload |
| def csr_matrix_from_dense_indices(indices: torch_.Tensor, n_cols: int) -> torch_.Tensor: |
| """Convert a regular indices array to a sparse CSR adjacency matrix format |
| |
| ## Parameters |
| - `indices` (Tensor): shape (N, M) dense tensor. Each one in `N` has `M` connections. |
| - `values` (Tensor): shape (N, M) values of the connections |
| - `n_cols` (int): total number of columns in the adjacency matrix |
| |
| ## Returns |
| Tensor: shape `(N, n_cols)` sparse CSR adjacency matrix""" |
| utils3d.torch.utils.csr_matrix_from_dense_indices |
|
|
| @overload |
| def csr_eliminate_zeros(input: torch_.Tensor): |
| """Remove zero elements from a sparse CSR tensor. |
| """ |
| utils3d.torch.utils.csr_eliminate_zeros |
|
|
| @overload |
| def group(labels: torch_.Tensor, data: Optional[torch_.Tensor] = None) -> List[Tuple[torch_.Tensor, torch_.Tensor]]: |
| """Split the data into groups based on the provided labels. |
| |
| ## Parameters |
| - `labels` (Tensor): shape `(N, *label_dims)` array of labels for each data point. Labels can be multi-dimensional. |
| - `data` (Tensor, optional): shape `(N, *data_dims)` dense tensor. Each one in `N` has `D` features. |
| If None, return the indices in each group instead. |
| |
| ## Returns |
| - `groups` (List[Tuple[Tensor, Tensor]]): List of each group, a tuple of `(label, data_in_group)`. |
| - `label` (Tensor): shape (*label_dims,) the label of the group. |
| - `data_in_group` (Tensor): shape (M, *data_dims) the data points in the group. |
| If `data` is None, `data_in_group` will be the indices of the data points in the original array.""" |
| utils3d.torch.utils.group |
|
|
| @overload |
| def lexsort(keys: Union[Sequence[torch_.Tensor], torch_.Tensor], dim: int = -1) -> torch_.Tensor: |
| """Perform lexicographical sort on multiple keys. Like `numpy.lexsort`. |
| |
| Given multiple sorting keys, lexsort returns an array of integer indices that describes the sort order by multiple keys. |
| The last key in the sequence is used for the primary sort order, ties are broken by the second-to-last key, and so on. |
| |
| Parameters |
| ---- |
| - `keys`: (Sequence[Tensor]) sequence of Tensors to sort by, or a single Tensor with shape `(num_keys, ...)`. |
| - `dim`: (int) the dimension to sort along. Note that if `keys` is a single Tensor, `dim=0` refers to the second dimension of `keys`. |
| |
| Returns |
| ---- |
| - `indices`: (Tensor) the indices that would sort the keys lexicographically along the specified dimension. |
| |
| Notes |
| ----- |
| Sorting is always stable.""" |
| utils3d.torch.utils.lexsort |
|
|
| @overload |
| def index_reduce(input: torch_.Tensor, indices: Union[Tuple[torch_.Tensor], List[torch_.Tensor]], values: torch_.Tensor, reduce: Literal['amin', 'amax', 'sum', 'prod', 'mean'], include_self: bool = True) -> torch_.Tensor: |
| """Put values into the input tensor at the specified indices (like `index_put`), with reduction support. |
| Behaves like `numpy.ufunc.at`. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) the input tensor to modify. |
| - `indices`: (Tensor) the indices at which to put the values. |
| - `values`: (Tensor) the values to put into the input tensor. |
| - `reduce`: (str) the reduction method to use when multiple values are put at the same index. Options are 'amin', 'amax', 'sum', 'prod', and 'mean'. |
| |
| Returns |
| ---- |
| - (Tensor) the modified tensor after putting the values.""" |
| utils3d.torch.utils.index_reduce |
|
|
| @overload |
| def index_reduce_(input: torch_.Tensor, indices: Union[Tuple[torch_.Tensor], List[torch_.Tensor]], values: torch_.Tensor, reduce: Literal['amin', 'amax', 'sum', 'prod', 'mean'], include_self: bool = True) -> torch_.Tensor: |
| """In-place put values into the input tensor at the specified indices (like `index_put_`), with reduction support. |
| Behaves like `numpy.ufunc.at`. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) the input tensor to modify. |
| - `indices`: (Tensor) the indices at which to put the values. |
| - `values`: (Tensor) the values to put into the input tensor. |
| - `reduce`: (str) the reduction method to use when multiple values are put at the same index. Options are 'amin', 'amax', 'sum', 'prod', and 'mean'. |
| |
| Returns |
| ---- |
| - (Tensor) the modified tensor after putting the values.""" |
| utils3d.torch.utils.index_reduce_ |
|
|
| @overload |
| def scatter_argmax(input: torch_.Tensor, dim: int, index: torch_.Tensor, src: torch_.Tensor, include_self: bool = True) -> torch_.Tensor: |
| """Scatter src into input at index along dim with min reduction. Return the indices of the winners in src. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) the input tensor to scatter into. |
| - `dim`: (int) the dimension along which to index. |
| - `index`: (LongTensor) the indices at which to scatter. |
| - `src`: (Tensor) the source tensor to scatter from. |
| - `include_self`: (bool) whether to include the original values in `input` when computing the min. |
| |
| Returns |
| ---- |
| - `argmin`: (LongTensor) shape same as `input`, the indices of the min values in `src`. |
| |
| Notes |
| ---- |
| - If multiple values in `src` are equal to the min value at a position, the one with the smallest index in `src` will be chosen. |
| - If none of src was scattered to a position (i.e., not presented, or the min value is from the original input), the index will be -1.""" |
| utils3d.torch.utils.scatter_argmax |
|
|
| @overload |
| def scatter_argmin(input: torch_.Tensor, dim: int, index: torch_.Tensor, src: torch_.Tensor, include_self: bool = True) -> torch_.Tensor: |
| """Scatter src into input at index along dim with min reduction. Return the indices of the winners in src. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) the input tensor to scatter into. |
| - `dim`: (int) the dimension along which to index. |
| - `index`: (LongTensor) the indices at which to scatter. |
| - `src`: (Tensor) the source tensor to scatter from. |
| - `include_self`: (bool) whether to include the original values in `input` when computing the min. |
| |
| Returns |
| ---- |
| - `argmin`: (LongTensor) shape same as `input`, the indices of the min values in `src`. |
| |
| Notes |
| ---- |
| - If multiple values in `src` are equal to the min value at a position, the one with the smallest index in `src` will be chosen. |
| - If none of src was scattered to a position (i.e., not presented, or the min value is from the original input), the index will be -1.""" |
| utils3d.torch.utils.scatter_argmin |
|
|
| @overload |
| def reverse_permutation(perm: torch_.Tensor, dim: int = 0) -> torch_.Tensor: |
| """Reverse a permutation tensor along a specified dimension. |
| Parameters |
| ---- |
| - `perm`: (LongTensor) the permutation tensor to reverse. |
| - `dim`: (int) the dimension of permutation indices. Other dimensions are treated as batch dimensions. |
| |
| Returns |
| ---- |
| - (LongTensor) the reversed permutation tensor, such that `reversed_perm[perm] == torch.arange(perm.shape[dim])` |
| |
| Notes |
| ----- |
| Equivalent to `torch.argsort(perm, dim=dim)`, but more efficient.""" |
| utils3d.torch.utils.reverse_permutation |
|
|
| @overload |
| def large_multinomial(weights: torch_.Tensor, num_samples: int, replacement: bool = False) -> torch_.Tensor: |
| utils3d.torch.utils.large_multinomial |
|
|
| @overload |
| def matrix_trace(input: torch_.Tensor, dim1: int = -2, dim2: int = -1) -> torch_.Tensor: |
| """Compute the trace of a batch of matrices""" |
| utils3d.torch.utils.matrix_trace |
|
|
| @overload |
| def vector_outer(x: torch_.Tensor, y: Optional[torch_.Tensor] = None) -> torch_.Tensor: |
| """Compute the outer product of two arrays. |
| |
| Parameters |
| ---- |
| - `x` (Tensor): shape `(..., M)` first array. |
| - `y` (Tensor, optional): shape `(..., N)` second array. If None, compute the outer product of `x` with itself. |
| |
| Returns |
| ---- |
| - `outer` (Tensor): shape `(..., M, N)` outer product of `x` and `y`.""" |
| utils3d.torch.utils.vector_outer |
|
|
| @overload |
| def perspective_from_fov(*, fov_x: Union[float, torch_.Tensor, NoneType] = None, fov_y: Union[float, torch_.Tensor, NoneType] = None, fov_min: Union[float, torch_.Tensor, NoneType] = None, fov_max: Union[float, torch_.Tensor, NoneType] = None, aspect_ratio: Union[float, torch_.Tensor, NoneType] = None, near: Union[float, torch_.Tensor, NoneType], far: Union[float, torch_.Tensor, NoneType]) -> torch_.Tensor: |
| """Get OpenGL perspective matrix from field of view |
| |
| ## Returns |
| (Tensor): [..., 4, 4] perspective matrix""" |
| utils3d.torch.transforms.perspective_from_fov |
|
|
| @overload |
| def perspective_from_window(left: Union[float, torch_.Tensor], right: Union[float, torch_.Tensor], bottom: Union[float, torch_.Tensor], top: Union[float, torch_.Tensor], near: Union[float, torch_.Tensor], far: Union[float, torch_.Tensor]) -> torch_.Tensor: |
| """Get OpenGL perspective matrix from the window of z=-1 projection plane |
| |
| ## Returns |
| (Tensor): [..., 4, 4] perspective matrix""" |
| utils3d.torch.transforms.perspective_from_window |
|
|
| @overload |
| def intrinsics_from_fov(*, fov_x: Union[float, torch_.Tensor, NoneType] = None, fov_y: Union[float, torch_.Tensor, NoneType] = None, fov_max: Union[float, torch_.Tensor, NoneType] = None, fov_min: Union[float, torch_.Tensor, NoneType] = None, cx: Union[float, torch_.Tensor] = 0.5, cy: Union[float, torch_.Tensor] = 0.5, aspect_ratio: Union[float, torch_.Tensor, NoneType] = None) -> torch_.Tensor: |
| """Get normalized OpenCV intrinsics matrix from given field of view. |
| You can provide either fov_x, fov_y, fov_max or fov_min and aspect_ratio |
| |
| Parameters |
| ---- |
| fov_x (float | Tensor): field of view in x axis |
| fov_y (float | Tensor): field of view in y axis |
| fov_max (float | Tensor): field of view in largest dimension |
| fov_min (float | Tensor): field of view in smallest dimension |
| cx (float | Tensor): principal point x coordinate |
| cy (float | Tensor): principal point y coordinate |
| aspect_ratio (float | Tensor): aspect ratio of the image |
| |
| Returns |
| ---- |
| (Tensor): [..., 3, 3] OpenCV intrinsics matrix""" |
| utils3d.torch.transforms.intrinsics_from_fov |
|
|
| @overload |
| def intrinsics_from_focal_center(fx: Union[float, torch_.Tensor], fy: Union[float, torch_.Tensor], cx: Union[float, torch_.Tensor], cy: Union[float, torch_.Tensor]) -> torch_.Tensor: |
| """Get OpenCV intrinsics matrix |
| |
| ## Parameters |
| focal_x (float | Tensor): focal length in x axis |
| focal_y (float | Tensor): focal length in y axis |
| cx (float | Tensor): principal point in x axis |
| cy (float | Tensor): principal point in y axis |
| |
| ## Returns |
| (Tensor): [..., 3, 3] OpenCV intrinsics matrix""" |
| utils3d.torch.transforms.intrinsics_from_focal_center |
|
|
| @overload |
| def focal_to_fov(focal: torch_.Tensor): |
| utils3d.torch.transforms.focal_to_fov |
|
|
| @overload |
| def fov_to_focal(fov: torch_.Tensor): |
| utils3d.torch.transforms.fov_to_focal |
|
|
| @overload |
| def intrinsics_to_fov(intrinsics: torch_.Tensor) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """NOTE: approximate FOV by assuming centered principal point""" |
| utils3d.torch.transforms.intrinsics_to_fov |
|
|
| @overload |
| def view_look_at(eye: torch_.Tensor, look_at: torch_.Tensor, up: torch_.Tensor) -> torch_.Tensor: |
| """Get OpenGL view matrix looking at something |
| |
| ## Parameters |
| eye (Tensor): [..., 3] the eye position |
| look_at (Tensor): [..., 3] the position to look at |
| up (Tensor): [..., 3] head up direction (y axis in screen space). Not necessarily othogonal to view direction |
| |
| ## Returns |
| (Tensor): [..., 4, 4], view matrix""" |
| utils3d.torch.transforms.view_look_at |
|
|
| @overload |
| def extrinsics_look_at(eye: torch_.Tensor, look_at: torch_.Tensor, up: torch_.Tensor) -> torch_.Tensor: |
| """Get OpenCV extrinsics matrix looking at something |
| |
| ## Parameters |
| eye (Tensor): [..., 3] the eye position |
| look_at (Tensor): [..., 3] the position to look at |
| up (Tensor): [..., 3] head up direction (-y axis in screen space). Not necessarily othogonal to view direction |
| |
| ## Returns |
| (Tensor): [..., 4, 4], extrinsics matrix""" |
| utils3d.torch.transforms.extrinsics_look_at |
|
|
| @overload |
| def perspective_to_intrinsics(perspective: torch_.Tensor) -> torch_.Tensor: |
| """OpenGL perspective matrix to OpenCV intrinsics |
| |
| ## Parameters |
| perspective (Tensor): [..., 4, 4] OpenGL perspective matrix |
| |
| ## Returns |
| (Tensor): shape [..., 3, 3] OpenCV intrinsics""" |
| utils3d.torch.transforms.perspective_to_intrinsics |
|
|
| @overload |
| def intrinsics_to_perspective(intrinsics: torch_.Tensor, near: Union[float, torch_.Tensor], far: Union[float, torch_.Tensor]) -> torch_.Tensor: |
| """OpenCV intrinsics to OpenGL perspective matrix |
| NOTE: not work for tile-shifting intrinsics currently |
| |
| ## Parameters |
| intrinsics (Tensor): [..., 3, 3] OpenCV intrinsics matrix |
| near (float | Tensor): [...] near plane to clip |
| far (float | Tensor): [...] far plane to clip |
| ## Returns |
| (Tensor): [..., 4, 4] OpenGL perspective matrix""" |
| utils3d.torch.transforms.intrinsics_to_perspective |
|
|
| @overload |
| def extrinsics_to_view(extrinsics: torch_.Tensor) -> torch_.Tensor: |
| """OpenCV camera extrinsics to OpenGL view matrix |
| |
| ## Parameters |
| extrinsics (Tensor): [..., 4, 4] OpenCV camera extrinsics matrix |
| |
| ## Returns |
| (Tensor): [..., 4, 4] OpenGL view matrix""" |
| utils3d.torch.transforms.extrinsics_to_view |
|
|
| @overload |
| def view_to_extrinsics(view: torch_.Tensor) -> torch_.Tensor: |
| """OpenGL view matrix to OpenCV camera extrinsics |
| |
| ## Parameters |
| view (Tensor): [..., 4, 4] OpenGL view matrix |
| |
| ## Returns |
| (Tensor): [..., 4, 4] OpenCV camera extrinsics matrix""" |
| utils3d.torch.transforms.view_to_extrinsics |
|
|
| @overload |
| def normalize_intrinsics(intrinsics: torch_.Tensor, size: Union[Tuple[numbers.Number, numbers.Number], torch_.Tensor], pixel_convention: Literal['integer-corner', 'integer-center'] = 'integer-center') -> torch_.Tensor: |
| """Normalize camera intrinsics to uv space |
| |
| ## Parameters |
| - `intrinsics` (Tensor): `(..., 3, 3)` camera intrinsics to normalize |
| - `size` (tuple | Tensor): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `pixel_convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - For more definitions, please refer to `pixel_coord_map()` |
| |
| ## Returns |
| (Tensor): [..., 3, 3] normalized camera intrinsics""" |
| utils3d.torch.transforms.normalize_intrinsics |
|
|
| @overload |
| def denormalize_intrinsics(intrinsics: torch_.Tensor, size: Union[Tuple[numbers.Number, numbers.Number], torch_.Tensor], pixel_convention: Literal['integer-center', 'integer-corner'] = 'integer-center') -> torch_.Tensor: |
| """Denormalize camera intrinsics(s) from uv space to pixel space |
| |
| ## Parameters |
| - `intrinsics` (Tensor): `(..., 3, 3)` camera intrinsics |
| - `size` (tuple | Tensor): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `pixel_convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - For more definitions, please refer to `pixel_coord_map()` |
| |
| ## Returns |
| (Tensor): [..., 3, 3] denormalized camera intrinsics in pixel space""" |
| utils3d.torch.transforms.denormalize_intrinsics |
|
|
| @overload |
| def crop_intrinsics(intrinsics: torch_.Tensor, size: Union[Tuple[numbers.Number, numbers.Number], torch_.Tensor], cropped_top: Union[numbers.Number, torch_.Tensor], cropped_left: Union[numbers.Number, torch_.Tensor], cropped_height: Union[numbers.Number, torch_.Tensor], cropped_width: Union[numbers.Number, torch_.Tensor]) -> torch_.Tensor: |
| """Evaluate the new intrinsics after cropping the image |
| |
| ## Parameters |
| intrinsics (Tensor): (..., 3, 3) camera intrinsics(s) to crop |
| height (int | Tensor): (...) image height(s) |
| width (int | Tensor): (...) image width(s) |
| cropped_top (int | Tensor): (...) top pixel index of the cropped image(s) |
| cropped_left (int | Tensor): (...) left pixel index of the cropped image(s) |
| cropped_height (int | Tensor): (...) height of the cropped image(s) |
| cropped_width (int | Tensor): (...) width of the cropped image(s) |
| |
| ## Returns |
| (Tensor): (..., 3, 3) cropped camera intrinsics""" |
| utils3d.torch.transforms.crop_intrinsics |
|
|
| @overload |
| def pixel_to_uv(pixel: torch_.Tensor, size: Union[Tuple[numbers.Number, numbers.Number], torch_.Tensor], pixel_convention: Literal['integer-corner', 'integer-center'] = 'integer-center') -> torch_.Tensor: |
| """## Parameters |
| - `pixel` (Tensor): `(..., 2)` pixel coordinrates |
| - `size` (tuple | Tensor): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `pixel_convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - For more definitions, please refer to `pixel_coord_map()` |
| |
| ## Returns |
| (Tensor): `(..., 2)` uv coordinrates""" |
| utils3d.torch.transforms.pixel_to_uv |
|
|
| @overload |
| def pixel_to_ndc(pixel: torch_.Tensor, size: Union[Tuple[numbers.Number, numbers.Number], torch_.Tensor], pixel_convention: Literal['integer-corner', 'integer-center'] = 'integer-center') -> torch_.Tensor: |
| """Convert pixel coordinates to NDC (Normalized Device Coordinates). |
| |
| ## Parameters |
| - `pixel` (Tensor): `(..., 2)` pixel coordinrates. |
| - `size` (tuple | Tensor): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `pixel_convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - For more definitions, please refer to `pixel_coord_map()` |
| |
| ## Returns |
| (Tensor): `(..., 2)` ndc coordinrates, the range is (-1, 1)""" |
| utils3d.torch.transforms.pixel_to_ndc |
|
|
| @overload |
| def uv_to_pixel(uv: torch_.Tensor, size: Union[Tuple[numbers.Number, numbers.Number], torch_.Tensor], pixel_convention: Literal['integer-corner', 'integer-center'] = 'integer-center') -> torch_.Tensor: |
| """Convert UV space coordinates to pixel space coordinates. |
| |
| ## Parameters |
| - `uv` (Tensor): `(..., 2)` uv coordinrates. |
| - `size` (tuple | Tensor): A tuple `(height, width)` of the image size, |
| or an array of shape `(..., 2)` corresponding to the multiple image size(s) |
| - `pixel_convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - For more definitions, please refer to `pixel_coord_map()` |
| |
| ## Returns |
| (Tensor): `(..., 2)` pixel coordinrates""" |
| utils3d.torch.transforms.uv_to_pixel |
|
|
| @overload |
| def depth_linear_to_buffer(depth: torch_.Tensor, near: Union[float, torch_.Tensor], far: Union[float, torch_.Tensor]) -> torch_.Tensor: |
| """Project linear depth to depth value in screen space |
| |
| ## Parameters |
| depth (Tensor): [...] depth value |
| near (float | Tensor): [...] near plane to clip |
| far (float | Tensor): [...] far plane to clip |
| |
| ## Returns |
| (Tensor): [..., 1] depth value in screen space, value ranging in [0, 1]""" |
| utils3d.torch.transforms.depth_linear_to_buffer |
|
|
| @overload |
| def depth_buffer_to_linear(depth: torch_.Tensor, near: Union[float, torch_.Tensor], far: Union[float, torch_.Tensor]) -> torch_.Tensor: |
| """Linearize depth value to linear depth |
| |
| ## Parameters |
| depth (Tensor): [...] screen depth value, ranging in [0, 1] |
| near (float | Tensor): [...] near plane to clip |
| far (float | Tensor): [...] far plane to clip |
| |
| ## Returns |
| (Tensor): [...] linear depth""" |
| utils3d.torch.transforms.depth_buffer_to_linear |
|
|
| @overload |
| def project_gl(points: torch_.Tensor, projection: torch_.Tensor, view: torch_.Tensor = None) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Project 3D points to 2D following the OpenGL convention (except for row major matrices) |
| |
| ## Parameters |
| points (Tensor): [..., N, 3] or [..., N, 4] 3D points to project, if the last |
| dimension is 4, the points are assumed to be in homogeneous coordinates |
| view (Tensor): [..., 4, 4] view matrix |
| projection (Tensor): [..., 4, 4] projection matrix |
| |
| ## Returns |
| scr_coord (Tensor): [..., N, 3] screen space coordinates, value ranging in [0, 1]. |
| The origin (0., 0., 0.) is corresponding to the left & bottom & nearest |
| linear_depth (Tensor): [..., N] linear depth""" |
| utils3d.torch.transforms.project_gl |
|
|
| @overload |
| def project_cv(points: torch_.Tensor, intrinsics: torch_.Tensor, extrinsics: Optional[torch_.Tensor] = None) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Project 3D points to 2D following the OpenCV convention |
| |
| ## Parameters |
| points (Tensor): [..., N, 3] 3D points |
| intrinsics (Tensor): [..., 3, 3] intrinsics matrix |
| extrinsics (Tensor): [..., 4, 4] extrinsics matrix |
| |
| ## Returns |
| uv_coord (Tensor): [..., N, 2] uv coordinates, value ranging in [0, 1]. |
| The origin (0., 0.) is corresponding to the left & top |
| linear_depth (Tensor): [..., N] linear depth""" |
| utils3d.torch.transforms.project_cv |
|
|
| @overload |
| def unproject_gl(uv: torch_.Tensor, depth: torch_.Tensor, projection: torch_.Tensor, view: Optional[torch_.Tensor] = None) -> torch_.Tensor: |
| """Unproject screen space coordinates to 3D view space following the OpenGL convention (except for row major matrices) |
| |
| ## Parameters |
| uv (Tensor): (..., N, 2) screen space XY coordinates, value ranging in [0, 1]. |
| The origin (0., 0.) is corresponding to the left & bottom |
| depth (Tensor): (..., N) linear depth values |
| projection (Tensor): (..., 4, 4) projection matrix |
| view (Tensor): (..., 4, 4) view matrix |
| |
| ## Returns |
| points (Tensor): (..., N, 3) 3d points""" |
| utils3d.torch.transforms.unproject_gl |
|
|
| @overload |
| def unproject_cv(uv: torch_.Tensor, depth: torch_.Tensor, intrinsics: torch_.Tensor, extrinsics: torch_.Tensor = None) -> torch_.Tensor: |
| """Unproject uv coordinates to 3D view space following the OpenCV convention |
| |
| ## Parameters |
| uv (Tensor): [..., N, 2] uv coordinates, value ranging in [0, 1]. |
| The origin (0., 0.) is corresponding to the left & top |
| depth (Tensor): [..., N] depth value |
| extrinsics (Tensor): [..., 4, 4] extrinsics matrix |
| intrinsics (Tensor): [..., 3, 3] intrinsics matrix |
| |
| ## Returns |
| points (Tensor): [..., N, 3] 3d points""" |
| utils3d.torch.transforms.unproject_cv |
|
|
| @overload |
| def project(points: torch_.Tensor, *, intrinsics: Optional[torch_.Tensor] = None, extrinsics: Optional[torch_.Tensor] = None, view: Optional[torch_.Tensor] = None, projection: Optional[torch_.Tensor] = None) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Calculate projection. |
| - For OpenCV convention, use `intrinsics` and `extrinsics` matrices. |
| - For OpenGL convention, use `view` and `projection` matrices. |
| |
| ## Parameters |
| |
| - `points`: (..., N, 3) 3D world-space points |
| - `intrinsics`: (..., 3, 3) intrinsics matrix |
| - `extrinsics`: (..., 4, 4) extrinsics matrix |
| - `view`: (..., 4, 4) view matrix |
| - `projection`: (..., 4, 4) projection matrix |
| |
| ## Returns |
| |
| - `uv`: (..., N, 2) 2D coordinates. |
| - For OpenCV convention, it is the normalized image coordinate where (0, 0) is the top left corner. |
| - For OpenGL convention, it is the screen space XY coordinate where (0, 0) is the bottom left corner. |
| - `depth`: (..., N) linear depth values, where `depth > 0` is visible. |
| - For OpenCV convention, it is the Z coordinate in camera space. |
| - For OpenGL convention, it is the -Z coordinate in camera space.""" |
| utils3d.torch.transforms.project |
|
|
| @overload |
| def unproject(uv: torch_.Tensor, depth: Optional[torch_.Tensor], *, intrinsics: Optional[torch_.Tensor] = None, extrinsics: Optional[torch_.Tensor] = None, projection: Optional[torch_.Tensor] = None, view: Optional[torch_.Tensor] = None) -> torch_.Tensor: |
| """Calculate inverse projection. |
| - For OpenCV convention, use `intrinsics` and `extrinsics` matrices. |
| - For OpenGL convention, use `view` and `projection` matrices. |
| |
| ## Parameters |
| |
| - `uv`: (..., N, 2) 2D coordinates. |
| - For OpenCV convention, it is the normalized image coordinate where (0, 0) is the top left corner. |
| - For OpenGL convention, it is the screen space XY coordinate where (0, 0) is the bottom left corner. |
| - `depth`: (..., N) linear depth values, where `depth > 0` is visible. |
| - For OpenCV convention, it is the Z coordinate in camera space. |
| - For OpenGL convention, it is the -Z coordinate in camera space. |
| - `intrinsics`: (..., 3, 3) intrinsics matrix |
| - `extrinsics`: (..., 4, 4) extrinsics matrix |
| - `view`: (..., 4, 4) view matrix |
| - `projection`: (..., 4, 4) projection matrix |
| |
| ## Returns |
| |
| - `points`: (..., N, 3) 3D world-space points""" |
| utils3d.torch.transforms.unproject |
|
|
| @overload |
| def skew_symmetric(v: torch_.Tensor): |
| """Skew symmetric matrix from a 3D vector""" |
| utils3d.torch.transforms.skew_symmetric |
|
|
| @overload |
| def rotation_matrix_from_vectors(v1: torch_.Tensor, v2: torch_.Tensor): |
| """Rotation matrix that rotates v1 to v2""" |
| utils3d.torch.transforms.rotation_matrix_from_vectors |
|
|
| @overload |
| def euler_axis_angle_rotation(axis: str, angle: torch_.Tensor) -> torch_.Tensor: |
| """Return the rotation matrices for one of the rotations about an axis |
| of which Euler angles describe, for each value of the angle given. |
| |
| ## Parameters |
| axis: Axis label "X" or "Y or "Z". |
| angle: any shape tensor of Euler angles in radians |
| |
| ## Returns |
| Rotation matrices as tensor of shape (..., 3, 3).""" |
| utils3d.torch.transforms.euler_axis_angle_rotation |
|
|
| @overload |
| def euler_angles_to_matrix(euler_angles: torch_.Tensor, convention: str = 'XYZ') -> torch_.Tensor: |
| """Convert rotations given as Euler angles in radians to rotation matrices. |
| |
| ## Parameters |
| euler_angles: Euler angles in radians as tensor of shape (..., 3), XYZ |
| convention: permutation of "X", "Y" or "Z", representing the order of Euler rotations to apply. |
| |
| ## Returns |
| Rotation matrices as tensor of shape (..., 3, 3).""" |
| utils3d.torch.transforms.euler_angles_to_matrix |
|
|
| @overload |
| def matrix_to_euler_angles(matrix: torch_.Tensor, convention: str) -> torch_.Tensor: |
| """Convert rotations given as rotation matrices to Euler angles in radians. |
| NOTE: The composition order eg. `XYZ` means `Rz * Ry * Rx` (like blender), instead of `Rx * Ry * Rz` (like pytorch3d) |
| |
| ## Parameters |
| matrix: Rotation matrices as tensor of shape (..., 3, 3). |
| convention: Convention string of three uppercase letters. |
| |
| ## Returns |
| Euler angles in radians as tensor of shape (..., 3), in the order of XYZ (like blender), instead of convention (like pytorch3d)""" |
| utils3d.torch.transforms.matrix_to_euler_angles |
|
|
| @overload |
| def matrix_to_quaternion(rot_mat: torch_.Tensor, eps: float = 1e-12) -> torch_.Tensor: |
| """Convert 3x3 rotation matrix to quaternion (w, x, y, z) |
| |
| ## Parameters |
| rot_mat (Tensor): shape (..., 3, 3), the rotation matrices to convert |
| |
| ## Returns |
| Tensor: shape (..., 4), the quaternions corresponding to the given rotation matrices""" |
| utils3d.torch.transforms.matrix_to_quaternion |
|
|
| @overload |
| def quaternion_to_matrix(quaternion: torch_.Tensor, eps: float = 1e-12) -> torch_.Tensor: |
| """Converts a batch of quaternions (w, x, y, z) to rotation matrices |
| |
| ## Parameters |
| quaternion (Tensor): shape (..., 4), the quaternions to convert |
| |
| ## Returns |
| Tensor: shape (..., 3, 3), the rotation matrices corresponding to the given quaternions""" |
| utils3d.torch.transforms.quaternion_to_matrix |
|
|
| @overload |
| def quaternion_multiply(q1: torch_.Tensor, q2: torch_.Tensor) -> torch_.Tensor: |
| """Multiplies two quaternions (w, x, y, z) |
| |
| Parameters |
| ---- |
| q1 (Tensor): shape (..., 4), the first quaternion |
| q2 (Tensor): shape (..., 4), the second quaternion |
| |
| Returns |
| ---- |
| Tensor: shape (..., 4), the product of the two quaternions""" |
| utils3d.torch.transforms.quaternion_multiply |
|
|
| @overload |
| def quaternion_inverse(quaternion: torch_.Tensor) -> torch_.Tensor: |
| """Calculate the inverse of a batch of quaternions (w, x, y, z) |
| |
| Parameters |
| ---- |
| quaternion (Tensor): shape (..., 4), the quaternions to invert |
| |
| Returns |
| ---- |
| Tensor: shape (..., 4), no normalization applied. It depends on the input quaternion.""" |
| utils3d.torch.transforms.quaternion_inverse |
|
|
| @overload |
| def quaternion_normalize(quaternion: torch_.Tensor, eps: float = 1e-12) -> torch_.Tensor: |
| """Normalize quaternions (w, x, y, z) to unit length and positive w component |
| |
| Parameters |
| ---- |
| quaternion (Tensor): shape (..., 4), the quaternions to normalize |
| |
| Returns |
| ---- |
| Tensor: shape (..., 4), the normalized quaternions with unit length and positive w component""" |
| utils3d.torch.transforms.quaternion_normalize |
|
|
| @overload |
| def matrix_to_axis_angle(rot_mat: torch_.Tensor, eps: float = 1e-12) -> torch_.Tensor: |
| """Convert a batch of 3x3 rotation matrices to axis-angle representation (rotation vector) |
| |
| ## Parameters |
| rot_mat (Tensor): shape (..., 3, 3), the rotation matrices to convert |
| |
| ## Returns |
| Tensor: shape (..., 3), the axis-angle vectors corresponding to the given rotation matrices""" |
| utils3d.torch.transforms.matrix_to_axis_angle |
|
|
| @overload |
| def axis_angle_to_matrix(axis_angle: torch_.Tensor, eps: float = 1e-12) -> torch_.Tensor: |
| """Convert axis-angle representation (rotation vector) to rotation matrix, whose direction is the axis of rotation and length is the angle of rotation |
| |
| ## Parameters |
| axis_angle (Tensor): shape (..., 3), axis-angle vcetors |
| |
| ## Returns |
| Tensor: shape (..., 3, 3) The rotation matrices for the given axis-angle parameters""" |
| utils3d.torch.transforms.axis_angle_to_matrix |
|
|
| @overload |
| def axis_angle_to_quaternion(axis_angle: torch_.Tensor, eps: float = 1e-12) -> torch_.Tensor: |
| """Convert axis-angle representation (rotation vector) to quaternion (w, x, y, z) |
| |
| ## Parameters |
| axis_angle (Tensor): shape (..., 3), axis-angle vcetors |
| |
| ## Returns |
| Tensor: shape (..., 4) The quaternions for the given axis-angle parameters""" |
| utils3d.torch.transforms.axis_angle_to_quaternion |
|
|
| @overload |
| def quaternion_to_axis_angle(quaternion: torch_.Tensor, eps: float = 1e-12) -> torch_.Tensor: |
| """Convert a batch of quaternions (w, x, y, z) to axis-angle representation (rotation vector) |
| |
| ## Parameters |
| quaternion (Tensor): shape (..., 4), the quaternions to convert |
| |
| ## Returns |
| Tensor: shape (..., 3), the axis-angle vectors corresponding to the given quaternions""" |
| utils3d.torch.transforms.quaternion_to_axis_angle |
|
|
| @overload |
| def make_affine_matrix(M: torch_.Tensor, t: torch_.Tensor): |
| """Make an affine transformation matrix from a linear matrix and a translation vector. |
| |
| ## Parameters |
| M (Tensor): [..., D, D] linear matrix (rotation, scaling or general deformation) |
| t (Tensor): [..., D] translation vector |
| |
| ## Returns |
| Tensor: [..., D + 1, D + 1] affine transformation matrix""" |
| utils3d.torch.transforms.make_affine_matrix |
|
|
| @overload |
| def random_rotation_matrix(*size: int, dtype=torch_.float32, device: torch_.device = None) -> torch_.Tensor: |
| """Generate random 3D rotation matrix. |
| |
| ## Parameters |
| dtype: The data type of the output rotation matrix. |
| |
| ## Returns |
| Tensor: `(*size, 3, 3)` random rotation matrix.""" |
| utils3d.torch.transforms.random_rotation_matrix |
|
|
| @overload |
| def lerp(v1: torch_.Tensor, v2: torch_.Tensor, t: torch_.Tensor) -> torch_.Tensor: |
| """Linear interpolation between two vectors. |
| |
| ## Parameters |
| - `v1` (Tensor): `(..., D)` vector 1 |
| - `v2` (Tensor): `(..., D)` vector 2 |
| - `t` (Tensor): `(..., N)` interpolation parameter in [0, 1] |
| |
| ## Returns |
| Tensor: `(..., N, D)` interpolated vector""" |
| utils3d.torch.transforms.lerp |
|
|
| @overload |
| def slerp(v1: torch_.Tensor, v2: torch_.Tensor, t: torch_.Tensor, eps: float = 1e-12) -> torch_.Tensor: |
| """Spherical linear interpolation between two (unit) vectors. |
| |
| ## Parameters |
| `v1` (Tensor): `(..., D)` (unit) vector 1 |
| `v2` (Tensor): `(..., D)` (unit) vector 2 |
| `t` (Tensor): `(..., N)` interpolation parameter in [0, 1] |
| |
| ## Returns |
| Tensor: `(..., N, D)` interpolated unit vector""" |
| utils3d.torch.transforms.slerp |
|
|
| @overload |
| def slerp_rotation_matrix(R1: torch_.Tensor, R2: torch_.Tensor, t: Union[numbers.Number, torch_.Tensor]) -> torch_.Tensor: |
| """Spherical linear interpolation between two 3D rotation matrices |
| |
| ## Parameters |
| R1 (Tensor): shape (..., 3, 3), the first rotation matrix |
| R2 (Tensor): shape (..., 3, 3), the second rotation matrix |
| t (Tensor): scalar or shape (..., N), the interpolation factor |
| |
| ## Returns |
| Tensor: shape (..., N, 3, 3), the interpolated rotation matrix""" |
| utils3d.torch.transforms.slerp_rotation_matrix |
|
|
| @overload |
| def interpolate_se3_matrix(T1: torch_.Tensor, T2: torch_.Tensor, t: torch_.Tensor): |
| """Interpolate between two SE(3) transformation matrices. |
| - Spherical linear interpolation (SLERP) is used for the rotational part. |
| - Linear interpolation is used for the translational part. |
| |
| ## Parameters |
| - `T1` (Tensor): (..., 4, 4) SE(3) matrix 1 |
| - `T2` (Tensor): (..., 4, 4) SE(3) matrix 2 |
| - `t` (Tensor): (..., N) interpolation parameter in [0, 1] |
| |
| ## Returns |
| Tensor: (..., N, 4, 4) interpolated SE(3) matrix""" |
| utils3d.torch.transforms.interpolate_se3_matrix |
|
|
| @overload |
| def extrinsics_to_essential(extrinsics: torch_.Tensor): |
| """extrinsics matrix `[[R, t] [0, 0, 0, 1]]` such that `x' = R (x - t)` to essential matrix such that `x' E x = 0` |
| |
| ## Parameters |
| extrinsics (Tensor): [..., 4, 4] extrinsics matrix |
| |
| ## Returns |
| (Tensor): [..., 3, 3] essential matrix""" |
| utils3d.torch.transforms.extrinsics_to_essential |
|
|
| @overload |
| def rotation_matrix_2d(theta: Union[float, torch_.Tensor]): |
| """2x2 matrix for 2D rotation |
| |
| ## Parameters |
| theta (float | Tensor): rotation angle in radians, arbitrary shape (...,) |
| |
| ## Returns |
| (Tensor): (..., 2, 2) rotation matrix""" |
| utils3d.torch.transforms.rotation_matrix_2d |
|
|
| @overload |
| def rotate_2d(theta: Union[float, torch_.Tensor], center: torch_.Tensor = None): |
| """3x3 matrix for 2D rotation around a center |
| ``` |
| [[Rxx, Rxy, tx], |
| [Ryx, Ryy, ty], |
| [0, 0, 1]] |
| ``` |
| ## Parameters |
| theta (float | Tensor): rotation angle in radians, arbitrary shape (...,) |
| center (Tensor): rotation center, arbitrary shape (..., 2). Default to (0, 0) |
| |
| ## Returns |
| (Tensor): (..., 3, 3) transformation matrix""" |
| utils3d.torch.transforms.rotate_2d |
|
|
| @overload |
| def translate_2d(translation: torch_.Tensor): |
| """Translation matrix for 2D translation |
| ``` |
| [[1, 0, tx], |
| [0, 1, ty], |
| [0, 0, 1]] |
| ``` |
| ## Parameters |
| translation (Tensor): translation vector, arbitrary shape (..., 2) |
| |
| ## Returns |
| (Tensor): (..., 3, 3) transformation matrix""" |
| utils3d.torch.transforms.translate_2d |
|
|
| @overload |
| def scale_2d(scale: Union[float, torch_.Tensor], center: torch_.Tensor = None): |
| """Scale matrix for 2D scaling |
| ``` |
| [[s, 0, tx], |
| [0, s, ty], |
| [0, 0, 1]] |
| ``` |
| ## Parameters |
| scale (float | Tensor): scale factor, arbitrary shape (...,) |
| center (Tensor): scale center, arbitrary shape (..., 2). Default to (0, 0) |
| |
| ## Returns |
| (Tensor): (..., 3, 3) transformation matrix""" |
| utils3d.torch.transforms.scale_2d |
|
|
| @overload |
| def transform_points(x: torch_.Tensor, *Ts: torch_.Tensor) -> torch_.Tensor: |
| """Apply transformation(s) to a point or a set of points. |
| It is like `(Tn @ ... @ T2 @ T1 @ x[:, None]).squeeze(0)`, but: |
| 1. Automatically handle the homogeneous coordinate; |
| - x will be padded with homogeneous coordinate 1. |
| - Each T will be padded by identity matrix to match the dimension. |
| 2. Using efficient contraction path when array sizes are large, based on `einsum`. |
| |
| ## Parameters |
| - `x`: Tensor, shape `(..., D)`: the points to be transformed. |
| - `Ts`: Tensor, shape `(..., D + 1, D + 1)`: the affine transformation matrix (matrices) |
| If more than one transformation is given, they will be applied in corresponding order. |
| ## Returns |
| - `y`: Tensor, shape `(..., D)`: the transformed point or a set of points. |
| |
| ## Example Usage |
| |
| - Just linear transformation |
| |
| ``` |
| y = transform(x_3, mat_3x3) |
| ``` |
| |
| - Affine transformation |
| |
| ``` |
| y = transform(x_3, mat_3x4) |
| ``` |
| |
| - Chain multiple transformations |
| |
| ``` |
| y = transform(x_3, T1_4x4, T2_3x4, T3_3x4) |
| ```""" |
| utils3d.torch.transforms.transform_points |
|
|
| @overload |
| def angle_between(v1: torch_.Tensor, v2: torch_.Tensor, eps: float = 1e-08) -> torch_.Tensor: |
| """Calculate the angle between two (batches of) vectors. |
| Better precision than using the arccos dot product directly. |
| |
| ## Parameters |
| - `v1`: Tensor, shape (..., D): the first vector. |
| - `v2`: Tensor, shape (..., D): the second vector. |
| - `eps`: float, optional: prevents zero angle difference (indifferentiable). |
| |
| ## Returns |
| `angle`: Tensor, shape (...): the angle between the two vectors.""" |
| utils3d.torch.transforms.angle_between |
|
|
| @overload |
| def kabasch(cov: torch_.Tensor, eps: float = 1e-12): |
| """Backward gradients friendly Kabasch method (compute rotation from input covarience matrix). |
| """ |
| utils3d.torch.pose.kabasch |
|
|
| @overload |
| def umeyama(cov_yx: torch_.Tensor, cov_xx: Optional[torch_.Tensor] = None, cov_yy: Optional[torch_.Tensor] = None, mean_x: Optional[torch_.Tensor] = None, mean_y: Optional[torch_.Tensor] = None, eps: float = 1e-12) -> Tuple[torch_.Tensor, torch_.Tensor, torch_.Tensor]: |
| """Umeyama method to solve for scale `s`, rotation `R` and translation `t` such that `y_i ~= s R x_i + t`. |
| |
| Parameters |
| ---- |
| - `cov_yx`: (..., 3, 3) covariance matrix between y and x points. |
| - `cov_xx`: (..., 3, 3) covariance matrix of x points. If None, no scaling is solved. |
| - `cov_yy`: (..., 3, 3) covariance matrix of y points. If None, no scaling is solved. |
| - `mean_x`: (..., 3) mean of x points. If None, no translation is solved. |
| - `mean_y`: (..., 3) mean of y points. If None, no translation is solved. |
| |
| Specifically, based on provided inputs: |
| |
| - To solve the rotation `R`, `cov_yx` must be given. |
| - To solve the scale `s`, at least one of `cov_xx` and `cov_yy` must be given. |
| - (Recommended) If both `cov_xx` and `cov_yy` are given, the scale will be solved by minimizing a symmetric cost: |
| `||s R X + t - Y||_F^2 / ||Y||_F^2 + ||s R^T (Y - t) - X||_F^2 / ||X||_F^2` |
| - If only `cov_xx` is given, the scale will be solved by minimizing forward cost |
| `||s R X + t - Y||_F^2` |
| - If only `cov_yy` is given, the scale will be solved by minimizing inverse cost |
| `||s R^T (Y - t) - X||_F^2` |
| - To solve the translation `t`, provide `mean_x` and `mean_y`. |
| |
| Returns |
| ---- |
| - `s`: (...) scale factor. None if both cov_xx and cov_yy are None. |
| - `R`: (..., 3, 3) rotation matrix. |
| - `t`: (..., 3) translation vector. None if mean_x or mean_y is None.""" |
| utils3d.torch.pose.umeyama |
|
|
| @overload |
| def affine_umeyama(cov_yx: torch_.Tensor, cov_xx: torch_.Tensor, cov_yy: torch_.Tensor, mean_x: torch_.Tensor, mean_y: torch_.Tensor, lam: float = 0.01, niter: int = 8, eps: float = 1e-12) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Extended Procrustes analysis to solve for affine transformation `A` and translation `t` such that `y_i ~= A x_i + t`. |
| |
| NOTE: This function is indifferentiable due to the iterative solving process. |
| |
| Parameters |
| ---- |
| - `cov_yx`: (..., 3, 3) covariance matrix between y and x points. |
| - `cov_xx`: (..., 3, 3) covariance matrix of x points. |
| - `cov_yy`: (..., 3, 3) covariance matrix of y points. |
| - `mean_x`: (..., 3) mean of x points. |
| - `mean_y`: (..., 3) mean of y points. |
| - `lam`: rigidity regularization weight. |
| - `gamma`: symmetricity regularization annealing factor. |
| - `niter`: number of iterations for solving. |
| |
| Returns |
| ---- |
| - `A`: (..., 3, 3) affine transformation matrix. |
| - `t`: (..., 3) translation vector.""" |
| utils3d.torch.pose.affine_umeyama |
|
|
| @overload |
| def solve_pose(p: torch_.Tensor, q: torch_.Tensor, w: Optional[torch_.Tensor] = None, *, mode: Literal['rigid', 'similar', 'affine'] = 'rigid', lam: float = 0.01, niter: int = 5, eps: float = 1e-12) -> torch_.Tensor: |
| """Solve for the pose (transformation from p to q) given weighted point correspondences. |
| |
| Parameters |
| ---- |
| - `p`: (..., N, 3) source points |
| - `q`: (..., N, 3) target points |
| - `w`: optional (..., N) weights for each point correspondence. If None, uniform weights are used. |
| - `mode`: mode of transformation to apply. Can be 'rigid', 'similar', or 'affine'. |
| - For 'rigid', only rotation and translation are allowed. |
| - For 'similar', uniform scaling, rotation and translation are allowed. |
| - For 'affine', full affine transformation is allowed. Using least squares. |
| - `lam`: regularization weight for 'affine' mode. |
| - `niter`: number of iterations for 'affine' mode. |
| - `eps`: small value to prevent division by zero. |
| |
| Returns |
| ---- |
| - `pose`: (..., 4, 4) transformations matrix from p to q.""" |
| utils3d.torch.pose.solve_pose |
|
|
| @overload |
| def segment_solve_pose(p: torch_.Tensor, q: torch_.Tensor, w: Optional[torch_.Tensor] = None, *, offsets: torch_.Tensor, mode: Literal['rigid', 'similar', 'affine'] = 'rigid', lam: float = 0.01, niter: int = 5, eps: float = 1e-12) -> torch_.Tensor: |
| """Solve for the pose (transformation from p to q: q ≈ pose @ p) given weighted point correspondences. |
| |
| NOTE: Affine mode is solved by iterative method and may be indifferentiable. Use with `torch.no_grad()` if you don't need gradients. |
| |
| Parameters |
| ---- |
| - `p`: (N, 3) source points |
| - `q`: (N, 3) target points |
| - `w`: (N,) weights for each point correspondence |
| - `offsets`: (S + 1,) segment offsets. Points in each segment belong to the same rigid / affine body. |
| - `mode`: mode of transformation to apply. Can be 'rigid', 'similar', or 'affine'. |
| - For 'rigid', only rotation and translation are allowed. |
| - For 'similar', uniform scaling, rotation and translation are allowed. |
| - For 'affine', full affine transformation is allowed. Using least squares. |
| - `lam`: regularization weight for 'affine' mode. |
| - `niter`: number of iterations for 'affine' mode. |
| - `eps`: small value to prevent division by zero. |
| |
| Returns |
| ---- |
| - `pose`: (S, 4, 4) transformations matrix from p to q.""" |
| utils3d.torch.pose.segment_solve_pose |
|
|
| @overload |
| def pose_graph_optimization(num_nodes: int, edges: torch_.Tensor, poses: torch_.Tensor, w: torch_.Tensor | None = None, niter: int = 10) -> tuple[torch_.Tensor, torch_.Tensor, torch_.Tensor]: |
| """Pose graph optimization to solve for global poses given relative poses (must be rigid transformations). |
| |
| Parameters |
| ---- |
| - `num_nodes`: number of nodes `N` in the pose graph. |
| - `edges`: (E, 2) edge list of the pose graph. Each edge is represented by a pair of node indices `i -> j`. |
| - `poses`: (E, 4, 4) relative poses of transformation from node `i` to node `j` for each edge. Must be rigid transformations. |
| - `w`: (E,) optional weights for each edge. |
| - `niter`: number of Procrustes iterations to refine global poses. If 0, only the initial solution by Laplacian SVD is returned. |
| |
| Returns |
| ---- |
| - `poses_global`: (N, 4, 4) global poses (world-to-camera, canonical-to-observation, global-to-node, etc.) for each node. |
| |
| `poses_relative[i->j] ≈ poses_global[j] @ poses_global[i].inv()`""" |
| utils3d.torch.pose.pose_graph_optimization |
|
|
| @overload |
| def segment_roll(data: torch_.Tensor, offsets: torch_.Tensor, shift: int, dim: int = 0) -> torch_.Tensor: |
| """Roll the data within each segment. |
| |
| Parameters |
| ------ |
| - `data`: (Tensor). |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of the segmented data. `M` is the number of segments. Starts with 0 and end with `data.shape[dim]`. |
| - `shift`: (int) the number of places by which elements are shifted. If negative, shift to left. |
| - `dim`: (int) the segment dimension to roll along. Default is 0. |
| |
| Returns |
| ------- |
| - `data`: (Tensor) the rolled data, same shape as input.""" |
| utils3d.torch.segment_ops.segment_roll |
|
|
| @overload |
| def segment_take(data: torch_.Tensor, offsets: torch_.Tensor, taking: torch_.Tensor, dim: int = 0) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Take some segments from a segmented array |
| |
| Parameters |
| ------ |
| - `data`: (Tensor) the segmented data. |
| - `offsets`: (Tensor) 1-D tensor of shape `(M + 1,)` the offsets of the segmented data. `M` is the number of segments. Starts with 0 and end with `data.shape[dim]`. |
| - `taking`: (Tensor) 1-D tensor of the indices of segments to take of shape `(K,)`, or boolean mask of shape `(M,)` |
| - `dim`: (int) the segment dimension to take along. Default is 0. Other dimensions are treated as batch dimensions. |
| |
| Returns |
| ------- |
| - `new_data`: (Tensor) the new segmented data. |
| - `new_offsets`: (Tensor) shape `(K + 1,)` the offsets of the new segmented data. `K` is the number of taken segments.""" |
| utils3d.torch.segment_ops.segment_take |
|
|
| @overload |
| def segment_concatenate(segments: Sequence[Tuple[torch_.Tensor, torch_.Tensor]], dim: int = 0) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Concatenate segmented arrays within each segment. All numbers of segments remain the same. |
| |
| Parameters |
| ------ |
| - `segments`: (Sequence[Tuple[Tensor, Tensor]]) A sequence of segmented arrays: |
| - `data`: (Tensor) shape `(..., N_i, ...)` |
| - `offsets`: (Tensor) shape `(M + 1,)` segment offsets. |
| - `axis`: (int) the segment axis. |
| |
| Returns |
| ------- |
| - `data`: (Tensor) shape `(..., sum(N_i), ...)` the concatenated data |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of the concatenated segmented data.""" |
| utils3d.torch.segment_ops.segment_concatenate |
|
|
| @overload |
| def segment_concat(segments: Sequence[Tuple[torch_.Tensor, torch_.Tensor]], axis: int = 0) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """(Alias for segment_concatenate). |
| Concatenate segmented arrays within each segment. |
| |
| Parameters |
| ------ |
| - `segments`: (Sequence[Tuple[Tensor, Tensor]]) A sequence of segmented arrays: |
| - `data`: (Tensor) shape `(..., N_i, ...)` |
| - `offsets`: (Tensor) shape `(M + 1,)` segment offsets. |
| - `axis`: (int) the segment axis. |
| |
| Returns |
| ------- |
| - `data`: (Tensor) shape `(N, *data_dims)` the concatenated data |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of the concatenated segmented data.""" |
| utils3d.torch.segment_ops.segment_concat |
|
|
| @overload |
| def segment_chain(segments: Sequence[Tuple[torch_.Tensor, torch_.Tensor]], axis: int = 0) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Concatenate segmented arrays in sequence. The number of segments are summed. |
| |
| Parameters |
| ------ |
| - `segments`: (Sequence[Tuple[Tensor, Tensor]]) A sequence of segmente arrays: |
| - `data`: (Tensor) shape `(..., N_i, ...)` |
| - `offsets`: (Tensor) shape `(M + 1,)` segment offsets. |
| - `axis`: (int) the segment axis. |
| |
| Returns |
| ------- |
| - `data`: (Tensor) shape `(..., sum(N_i), ...)` the chain-concatenated data |
| - `offsets`: (Tensor) shape `(sum(M_i) + 1,)` the offsets of the concatenated segmented data.""" |
| utils3d.torch.segment_ops.segment_chain |
|
|
| @overload |
| def segment_argmax(data: torch_.Tensor, offsets: torch_.Tensor, dim: int = 0) -> torch_.Tensor: |
| """Compute the argmax of each segment in the segmented data. |
| |
| Parameters |
| ---------- |
| - `data`: (Tensor) shape `(..., N, ...)` the data to compute argmax from. If `data` may have multiple dimensions, extra dimensions are treated as batch dimensions. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of the segmented data |
| - `dim`: (int) the segment axis to compute along. Default is 0. |
| |
| Returns |
| ------- |
| - `argmax_indices`: (Tensor) shape `(..., M, ...)` the argmax indices of each segment along the first dimension. |
| |
| NOTE: If there are multiple maximum values in a segment, the index of the first one is returned. If a segment is empty, -1 is returned.""" |
| utils3d.torch.segment_ops.segment_argmax |
|
|
| @overload |
| def segment_argmin(data: torch_.Tensor, offsets: torch_.Tensor, dim: int = 0) -> torch_.Tensor: |
| """Compute the argmin of each segment in the segmented data. |
| |
| Parameters |
| ---------- |
| - `data`: (Tensor) shape `(..., N, ...)` the data to compute argmin from. If `data` may have multiple dimensionsm, extra dimensions are treated as batch dimensions. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of the segmented data |
| - `dim`: (int) the segment axis to compute along. Default is 0. |
| Returns |
| ------- |
| - `argmin_indices`: (Tensor) shape `(..., M, ...)` the argmin indices of each segment along the first dimension. |
| |
| NOTE: If there are multiple minimum values in a segment, the index of the first one is returned. If a segment is empty, -1 is returned.""" |
| utils3d.torch.segment_ops.segment_argmin |
|
|
| @overload |
| def segment_median(input: torch_.Tensor, offsets: torch_.Tensor, dim: int = 0) -> torch_.return_types.median: |
| """Compute the median of each segment. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) shape `(..., N, ...)` the data to compute median from. The first dimension is treated as the segment dimension. Extra dimensions are treated as batch dimensions. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of each segment. |
| - `dim`: (int) the segment axis to compute along. Default is 0. |
| |
| Returns |
| ---- |
| - `medians`: (Tensor) shape `(..., M, ...)` the median of each segment. |
| - `indices`: (Tensor) shape `(..., M, ...)` the indices of the median values in the original input. |
| |
| Notes |
| ----- |
| - If a segment has even length, the lower median is returned. |
| - If a segment is empty or has negative length, the median value is undefined.""" |
| utils3d.torch.segment_ops.segment_median |
|
|
| @overload |
| def segment_sum(input: torch_.Tensor, offsets: torch_.Tensor, dim: int = 0) -> torch_.Tensor: |
| """Compute the sum of each segment in the segmented data. Workaround supports for dtypes other than float32. |
| |
| NOTE: Silently assumes that the input does not contain negative lengths. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) shape `(..., N, ...)` the data to compute sum from. If `input` may have multiple dimensionsm, extra dimensions are treated as batch dimensions. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of the segmented data |
| - `dim`: (int) the segment axis to compute sum along. Default is 0. |
| |
| Returns |
| ---- |
| - `segment_sums`: (Tensor) shape `(..., M, ...)` the sum of each segment along the specified dimension.""" |
| utils3d.torch.segment_ops.segment_sum |
|
|
| @overload |
| def segment_cumsum(input: torch_.Tensor, offsets: torch_.Tensor, dim: int) -> torch_.Tensor: |
| """Compute the sum of each segment in the segmented data. Workaround supports for dtypes other than float32. |
| |
| NOTE: Silently assumes that the input does not contain negative lengths. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) shape `(..., N, ...)` the data to compute sum from. If `input` may have multiple dimensionsm, extra dimensions are treated as batch dimensions. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of the segmented data |
| |
| Returns |
| ---- |
| - `segment_sums`: (Tensor) shape `(..., N, ...)` the cumulative sum of each segment along the specified dimension.""" |
| utils3d.torch.segment_ops.segment_cumsum |
|
|
| @overload |
| def group_as_segments(labels: torch_.Tensor, data: Optional[torch_.Tensor] = None, return_inverse: bool = False, return_group_ids: bool = False) -> Tuple[torch_.Tensor, ...]: |
| """Group as segments by labels |
| |
| Parameters |
| ---- |
| - `labels` (Tensor): shape `(N, *label_dims)` array of labels for each data point. Labels can be multi-dimensional. |
| - `data` (Tensor, optional): shape `(N, *data_dims)` array. |
| If None, return the indices in each group instead. |
| |
| Returns |
| ------- |
| Assuming there are `M` difference labels: |
| |
| - `grouped_labels`: `(Tensor)` shape `(M, *label_dims)` labels of of each segment |
| - `grouped_data`: `(Tensor)` shape `(N,)` or `(N, *data_dims)` the rearranged data (or indices) where the same labels are grouped as a continous segment. |
| - `offsets`: `(Tensor)` shape `(M + 1,)`. `grouped_data[offsets[i]:offsets[i + 1]]` corresponding to the i-th segment whose label is `grouped_labels[i]` |
| - `inverse_indices` (Tensor, optional): shape `(N,)`. `data[inverse_indices]` recovers the original data order, |
| i.e., `inverse_indices[i]` gives the position that `data[i]` goes to in the `grouped_data`. |
| - `group_ids` (Tensor, optional): shape `(N,)`. The group id for each data point in the original order, |
| i.e., `group_ids[i]` gives the group index that `data[i]` belongs to. """ |
| utils3d.torch.segment_ops.group_as_segments |
|
|
| @overload |
| def segment_sort(input: torch_.Tensor, offsets: torch_.Tensor = None, descending: bool = False, dim: int = -1) -> torch_.return_types.sort: |
| """Sort the data within each segment. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) shape `(..., N, ...)` the data to sort. |
| - `lengths`: (Tensor) shape `(M,)` the lengths of each segment, alternatively to `offsets`. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets |
| - `descending`: (bool) whether to sort in descending order. |
| - `dim`: (int) the segment axis to sort along. Default is -1. |
| |
| Returns |
| ---- |
| - `sorted`: (Tensor) shape `(..., N, ...)` the sorted data. |
| - `indices`: (Tensor) shape `(..., N, ...)` the indices that would sort the data within each segment.""" |
| utils3d.torch.segment_ops.segment_sort |
|
|
| @overload |
| def segment_argsort(input: torch_.Tensor, offsets: torch_.Tensor, descending: bool = False, dim: int = -1) -> torch_.Tensor: |
| """Compute the argsort indices within each segment. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) shape `(..., N, ...)` the data to sort. The first dimension is treated as the segment dimension. Extra dimensions are treated as batch dimensions. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of each segment. |
| - `descending`: (bool) whether to sort in descending order. |
| - `dim`: (int) the segment axis to sort along. Default is -1. |
| |
| Returns |
| ---- |
| - `sorted_indices`: (Tensor) shape `(..., N, ...)` the indices that would sort the data within each segment.""" |
| utils3d.torch.segment_ops.segment_argsort |
|
|
| @overload |
| def segment_topk(input: torch_.Tensor, offsets: torch_.Tensor, k: Union[int, torch_.Tensor], largest: bool = True, dim: int = -1) -> Tuple[torch_.return_types.topk, torch_.Tensor]: |
| """Select the top-k values and indices within each segment. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) shape `(..., N, ...)` the data to compute top |
| - `k`: (int or Tensor) the number of top elements to retrieve from each segment. If a Tensor, it should have shape `(M,)` where `M` is the number of segments. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of each segment. |
| - `largest`: (bool) whether to return the largest or smallest elements. Otherwise, return the smallest elements. |
| - `dim`: (int) the segment axis to compute along. Default is -1. |
| |
| Returns |
| ---- |
| - `topk`: (namedtuple) with fields `values` and `indices`. |
| - `values`: (Tensor) shape `(sum_k, ...)` the top-k values where `sum_k` is the sum of all k's across segments. |
| - `indices`: (Tensor) shape `(sum_k, ...)` the indices of the top-k values in the original input. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of the top-k values for each segment. |
| |
| Notes |
| ----- |
| - If the length of a segment is less than k, the returns will contain all elements in that segment but fewer than k elements.""" |
| utils3d.torch.segment_ops.segment_topk |
|
|
| @overload |
| def stack_segments(input: torch_.Tensor, offsets: torch_.Tensor, max_length: int = None, padding_value: numbers.Number = 0, dim: int = 0) -> Tuple[torch_.Tensor, torch_.Tensor, torch_.Tensor]: |
| """Stack segments into a padded tensor. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) shape `(..., N, ...)` the data to stack. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of each segment. |
| - `max_length`: (int, optional) the maximum length to pad/truncate each segment to. If None, use the maximum segment length. |
| - `padding_value`: (Number) the value to use for padding. |
| - `dim`: (int) the segment axis to stack along. Default is 0. |
| |
| Returns |
| ---- |
| - `stacked`: (Tensor) shape `(..., M, max_length, ...)` the stacked segments, where `max_length` is the maximum segment length. |
| - `mask`: (Tensor) shape `(..., M, max_length)` boolean mask indicating valid entries in `stacked`. |
| - `indices`: (Tensor) shape `(..., M, max_length)` the indices of the stacked entries in the original input.""" |
| utils3d.torch.segment_ops.stack_segments |
|
|
| @overload |
| def segment_multinomial(weights: torch_.Tensor, offsets: torch_.Tensor, num_samples: torch_.Tensor, eps: float = 1e-12, replacement: bool = False) -> torch_.LongTensor: |
| """Perform multinomial sampling within each segment. |
| |
| Parameters |
| ---- |
| - `weights`: (Tensor) 1-D tensor of shape `(N,)` the weights for sampling. |
| - `offsets`: (Tensor) 1-D tensor of shape `(M + 1,)` the offsets of each segment. |
| - `n`: (int) the number of samples to draw from each segment. |
| - `eps`: (float) a small value to avoid division by zero. |
| - `replacement`: (bool) whether to sample with replacement. |
| |
| Returns |
| ---- |
| - `sampled_indices`: (LongTensor) shape `(tot_samples,)` the sampled indices from each segment. |
| - `offsets`: (LongTensor) shape `(M + 1,)` the offsets of the sampled indices for each segment.""" |
| utils3d.torch.segment_ops.segment_multinomial |
|
|
| @overload |
| def segment_combinations(input: torch_.Tensor, offsets: torch_.Tensor, r: int = 2, with_replacement: bool = False) -> torch_.Tensor: |
| """Generate all combinations of elements within each segment. Vectorized implementation. |
| |
| Parameters |
| ---- |
| - `input`: (Tensor) shape `(N,)` the data to generate combinations from. The first dimension is treated as the segment dimension. Extra dimensions are treated as batch dimensions. |
| - `offsets`: (Tensor) shape `(M + 1,)` the offsets of each segment. |
| - `r`: (int) the number of elements in each combination. |
| - `with_replacement`: (bool) whether to allow repeated elements in a combination. |
| |
| Returns |
| ---- |
| - `combinations`: (Tensor) shape `(K, r,)` the combinations from all segments, where `K` is the total number of combinations across all segments. |
| - `combination_offsets`: (Tensor) shape `(M + 1,)` the offsets of combinations for each segment. |
| |
| Notes |
| ---- |
| - The result may contain zero-length segments if a segment has less than `r` elements.""" |
| utils3d.torch.segment_ops.segment_combinations |
|
|
| @overload |
| def segment_searchsorted(sorted_sequence: torch_.Tensor, offsets: torch_.Tensor, input: torch_.Tensor, segment_ids: torch_.Tensor, side: Literal['left', 'right'] = 'left') -> torch_.Tensor: |
| """Per-segment searchsorted operation implemented with triton. |
| |
| Parameters |
| ---------- |
| - `sorted_sequence: Tensor` of shape (..., N), the concatenated sorted sequences of all segments. |
| - `offsets: Tensor` of shape (M + 1,), segment offsets applied to the last dimension of `sorted_sequence`. |
| - `input: Tensor` of shape (..., Q), the values to search for. |
| - `segment_ids: Tensor` of shape (..., Q), the segment ids to search within for each value in `input`. |
| |
| Returns |
| - `indices: Tensor` of shape (..., Q), the insertion indices for each value in `input` within its corresponding segment in `sorted_sequence`.""" |
| utils3d.torch.segment_ops.segment_searchsorted |
|
|
| @overload |
| def triangulate_mesh(faces: torch_.Tensor, vertices: torch_.Tensor = None, method: Literal['fan', 'strip', 'diagonal'] = 'fan') -> torch_.Tensor: |
| """Triangulate a polygonal mesh. |
| |
| ## Parameters |
| - `faces` (Tensor): [L, P] polygonal faces |
| - `vertices` (Tensor, optional): [N, 3] 3-dimensional vertices. |
| If given, the triangulation is performed according to the distance |
| between vertices. Defaults to None. |
| - `method` |
| |
| ## Returns |
| (Tensor): [L * (P - 2), 3] triangular faces""" |
| utils3d.torch.mesh.triangulate_mesh |
|
|
| @overload |
| def compute_face_corner_angles(vertices: torch_.Tensor, faces: Optional[torch_.Tensor] = None) -> torch_.Tensor: |
| """Compute face corner angles of a mesh |
| |
| ## Parameters |
| - `vertices` (Tensor): `(..., N, 3)` vertices if `faces` is provided, or `(..., F, P, 3)` if `faces` is None |
| - `faces` (Tensor, optional): `(F, P)` face vertex indices, where P is the number of vertices per face |
| |
| ## Returns |
| - `angles` (Tensor): `(..., F, P)` face corner angles""" |
| utils3d.torch.mesh.compute_face_corner_angles |
|
|
| @overload |
| def compute_face_corner_normals(vertices: torch_.Tensor, faces: Optional[torch_.Tensor] = None, normalize: bool = True) -> torch_.Tensor: |
| """Compute the face corner normals of a mesh |
| |
| ## Parameters |
| - `vertices` (Tensor): `(..., N, 3)` vertices if `faces` is provided, or `(..., F, P, 3)` if `faces` is None |
| - `faces` (Tensor, optional): `(F, P)` face vertex indices, where P is the number of vertices per face |
| - `normalize` (bool): whether to normalize the normals to unit vectors. If not, the normals are the raw cross products. |
| |
| ## Returns |
| - `normals` (Tensor): (..., F, P, 3) face corner normals""" |
| utils3d.torch.mesh.compute_face_corner_normals |
|
|
| @overload |
| def compute_face_corner_tangents(vertices: torch_.Tensor, uv: torch_.Tensor, faces_vertices: Optional[torch_.Tensor] = None, faces_uv: Optional[torch_.Tensor] = None, normalize: bool = True) -> torch_.Tensor: |
| """ Compute the face corner tangent (and bitangent) vectors of a mesh |
| |
| ## Parameters |
| - `vertices` (Tensor): `(..., N, 3)` if `faces` is provided, or `(..., F, P, 3)` if `faces_vertices` is None |
| - `uv` (Tensor): `(..., N, 2)` if `faces` is provided, or `(..., F, P, 2)` if `faces_uv` is None |
| - `faces_vertices` (Tensor, optional): `(F, P)` face vertex indices |
| - `faces_uv` (Tensor, optional): `(F, P)` face UV indices |
| - `normalize` (bool): whether to normalize the tangents to unit vectors. If not, the tangents (dX/du, dX/dv) matches the UV parameterized manifold. |
| s |
| ## Returns |
| - `tangents` (Tensor): `(..., F, P, 3, 2)` face corner tangents (and bitangents), |
| where the last dimension represents the tangent and bitangent vectors. |
| """ |
| utils3d.torch.mesh.compute_face_corner_tangents |
|
|
| @overload |
| def compute_face_normals(vertices: torch_.Tensor, faces: Optional[torch_.Tensor] = None) -> torch_.Tensor: |
| """Compute face normals of a mesh |
| |
| ## Parameters |
| - `vertices` (Tensor): `(..., N, 3)` vertices if `faces` is provided, or `(..., F, P, 3)` if `faces` is None |
| - `faces` (Tensor, optional): `(F, P)` face vertex indices, where P is the number of vertices per face |
| |
| ## Returns |
| - `normals` (Tensor): `(..., F, 3)` face normals. Always normalized.""" |
| utils3d.torch.mesh.compute_face_normals |
|
|
| @overload |
| def compute_face_tangents(vertices: torch_.Tensor, uv: torch_.Tensor, faces_vertices: Optional[torch_.Tensor] = None, faces_uv: Optional[torch_.Tensor] = None, normalize: bool = True) -> torch_.Tensor: |
| """Compute the face corner tangent (and bitangent) vectors of a mesh |
| |
| ## Parameters |
| - `vertices` (Tensor): `(..., N, 3)` if `faces` is provided, or `(..., F, P, 3)` if `faces_vertices` is None |
| - `uv` (Tensor): `(..., N, 2)` if `faces` is provided, or `(..., F, P, 2)` if `faces_uv` is None |
| - `faces_vertices` (Tensor, optional): `(F, P)` face vertex indices |
| - `faces_uv` (Tensor, optional): `(F, P)` face UV indices |
| |
| ## Returns |
| - `tangents` (Tensor): `(..., F, 3, 2)` face corner tangents (and bitangents), |
| where the last dimension represents the tangent and bitangent vectors.""" |
| utils3d.torch.mesh.compute_face_tangents |
|
|
| @overload |
| def mesh_edges(faces: torch_.Tensor, return_face2edge: bool = False, return_edge2face: bool = False, return_counts: bool = False) -> Tuple[torch_.Tensor, torch_.Tensor, torch_.Tensor, torch_.Tensor]: |
| """Get undirected edges of a mesh. Optionally return additional mappings. |
| |
| ## Parameters |
| - `faces` (Tensor): polygon faces |
| - `(F, P)` dense array of indices, where each face has `P` vertices. |
| - `(F, V)` binary sparse csr array of indices, each row corresponds to the vertices of a face. |
| - `return_face2edge` (bool): whether to return the face to edge mapping |
| - `return_edge2face` (bool): whether to return the edge to face mapping |
| - `return_counts` (bool): whether to return the counts of edges |
| |
| ## Returns |
| - `edges` (Tensor): `(E, 2)` unique edges' vertex indices |
| |
| If `return_face2edge`, `return_edge2face`, `return_opposite_edge`, or `return_counts` is True, the corresponding outputs will be appended in order: |
| |
| - `face2edge` (Tensor): mapping from faces to the indices of edges |
| - `(F, P)` if input `faces` is a dense array |
| - `(F, E)` if input `faces` is a sparse csr array |
| - `edge2face` (Tensor): `(E, F)` binary sparse CSR matrix of edge to face. |
| - `counts` (Tensor): `(E,)` counts of each edge""" |
| utils3d.torch.mesh.mesh_edges |
|
|
| @overload |
| def mesh_half_edges(faces: torch_.Tensor, return_face2edge: bool = False, return_edge2face: bool = False, return_twin: bool = False, return_next: bool = False, return_prev: bool = False, return_counts: bool = False) -> Tuple[torch_.Tensor, torch_.Tensor, torch_.Tensor, torch_.Tensor, torch_.Tensor, torch_.Tensor, torch_.Tensor]: |
| """Get half edges of a mesh. Optionally return additional mappings. |
| |
| ## Parameters |
| - `faces` (Tensor): polygon faces |
| - `(F, P)` dense array of indices, where each face has `P` vertices. |
| - `(F, V)` binary sparse csr array of indices, each row corresponds to the vertices of a face. |
| - `return_face2edge` (bool): whether to return the face to edge mapping |
| - `return_edge2face` (bool): whether to return the edge to face mapping |
| - `return_twin` (bool): whether to return the mapping from one edge to its opposite/twin edge |
| - `return_next` (bool): whether to return the mapping from one edge to its next edge in the face loop |
| - `return_prev` (bool): whether to return the mapping from one edge to its previous edge in the face loop |
| - `return_counts` (bool): whether to return the counts of edges |
| |
| ## Returns |
| - `edges` (Tensor): `(E, 2)` unique edges' vertex indices |
| |
| If `return_face2edge`, `return_edge2face`, `return_opposite_edge`, or `return_counts` is True, the corresponding outputs will be appended in order: |
| |
| - `face2edge` (Tensor | Tensor): mapping from faces to the indices of edges |
| - `(F, P)` if input `faces` is a dense array |
| - `(F, E)` if input `faces` is a sparse csr array |
| - `edge2face` (Tensor): `(E, F)` binary sparse CSR matrix of edge to face. |
| - `twin` (Tensor): `(E,)` mapping from edges to indices of opposite edges. -1 if not found. |
| - `next` (Tensor): `(E,)` mapping from edges to indices of next edges in the face loop. |
| - `prev` (Tensor): `(E,)` mapping from edges to indices of previous edges in the face loop. |
| - `counts` (Tensor): `(E,)` counts of each half edge |
| |
| NOTE: If the mesh is not manifold, `twin`, `next`, and `prev` can point to arbitrary one of the candidates.""" |
| utils3d.torch.mesh.mesh_half_edges |
|
|
| @overload |
| def mesh_dual_graph(faces: torch_.Tensor) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Get dual graph of a mesh. (Mesh face as dual graph's vertex, adjacency by edge sharing) |
| |
| ## Parameters |
| - `faces`: `Tensor` faces indices |
| - `(F, P)` dense tensor |
| |
| ## Returns |
| - `dual_graph` (Tensor): `(F, F)` binary sparse CSR matrix. Adjacency matrix of the dual graph.""" |
| utils3d.torch.mesh.mesh_dual_graph |
|
|
| @overload |
| def mesh_connected_components(faces: torch_.Tensor, num_vertices: Optional[int] = None) -> List[torch_.Tensor]: |
| """Compute connected components of a mesh. |
| |
| ## Parameters |
| - `faces` (Tensor): polygon faces |
| - `(F, P)` dense tensor of indices, where each face has `P` vertices. |
| - `(F, V)` binary sparse csr tensor of indices, each row corresponds to the vertices of a face. |
| - `num_vertices` (int, optional): total number of vertices. If given, the returned components will include all vertices. Defaults to None. |
| |
| ## Returns |
| |
| If `num_vertices` is given, return: |
| - `labels` (Tensor): (N,) component labels of each vertex |
| |
| If `num_vertices` is None, return: |
| - `vertices_ids` (Tensor): (N,) vertex indices that are in the edges |
| - `labels` (Tensor): (N,) component labels corresponding to `vertices_ids`""" |
| utils3d.torch.mesh.mesh_connected_components |
|
|
| @overload |
| def graph_connected_components(edges: torch_.Tensor, num_vertices: Optional[int] = None) -> Union[torch_.Tensor, Tuple[torch_.Tensor, torch_.Tensor]]: |
| """Compute connected components of an undirected graph. |
| |
| ## Parameters |
| - `edges` (Tensor): (E, 2) edge indices |
| |
| ## Returns |
| |
| If `num_vertices` is given, return: |
| - `labels` (Tensor): (N,) component labels of each vertex |
| |
| If `num_vertices` is None, return: |
| - `vertices_ids` (Tensor): (N,) vertex indices that are in the edges |
| - `labels` (Tensor): (N,) component labels corresponding to `vertices_ids`""" |
| utils3d.torch.mesh.graph_connected_components |
|
|
| @overload |
| def compute_boundaries(faces: torch_.Tensor, edges: torch_.Tensor = None, face2edge: torch_.Tensor = None, edge_degrees: torch_.Tensor = None) -> Tuple[List[torch_.Tensor], List[torch_.Tensor]]: |
| """Compute boundary edges of a mesh. |
| |
| ## Parameters |
| faces (Tensor): [T, 3] triangular face indices |
| edges (Tensor): [E, 2] edge indices. |
| face2edge (Tensor): [T, 3] mapping from face to edge. |
| edge_degrees (Tensor): [E] degree of each edge. |
| |
| ## Returns |
| boundary_edge_indices (List[Tensor]): list of boundary edge indices |
| boundary_face_indices (List[Tensor]): list of boundary face indices""" |
| utils3d.torch.mesh.compute_boundaries |
|
|
| @overload |
| def remove_unused_vertices(faces: torch_.Tensor, *vertice_attrs, return_indices: bool = False) -> Tuple[torch_.Tensor, ...]: |
| """Remove unreferenced vertices of a mesh. |
| Unreferenced vertices are removed, and the face indices are updated accordingly. |
| |
| ## Parameters |
| faces (Tensor): [T, P] face indices |
| *vertice_attrs: vertex attributes |
| |
| ## Returns |
| faces (Tensor): [T, P] face indices |
| *vertice_attrs: vertex attributes |
| indices (Tensor, optional): [N] indices of vertices that are kept. Defaults to None.""" |
| utils3d.torch.mesh.remove_unused_vertices |
|
|
| @overload |
| def remove_corrupted_faces(faces: torch_.Tensor) -> torch_.Tensor: |
| """Remove corrupted faces (faces with duplicated vertices) |
| |
| ## Parameters |
| faces (Tensor): [F, 3] face indices |
| |
| ## Returns |
| Tensor: [F_reduced, 3] face indices""" |
| utils3d.torch.mesh.remove_corrupted_faces |
|
|
| @overload |
| def remove_isolated_pieces(vertices: torch_.Tensor, faces: torch_.Tensor, connected_components: List[torch_.Tensor] = None, thresh_num_faces: int = None, thresh_radius: float = None, thresh_boundary_ratio: float = None, remove_unreferenced: bool = True) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Remove isolated pieces of a mesh. |
| Isolated pieces are removed, and the face indices are updated accordingly. |
| If no face is left, will return the largest connected component. |
| |
| ## Parameters |
| vertices (Tensor): [N, 3] 3-dimensional vertices |
| faces (Tensor): [T, 3] triangular face indices |
| connected_components (List[Tensor], optional): connected components of the mesh. If None, it will be computed. Defaults to None. |
| thresh_num_faces (int, optional): threshold of number of faces for isolated pieces. Defaults to None. |
| thresh_radius (float, optional): threshold of radius for isolated pieces. Defaults to None. |
| remove_unreferenced (bool, optional): remove unreferenced vertices after removing isolated pieces. Defaults to True. |
| |
| ## Returns |
| vertices (Tensor): [N_, 3] 3-dimensional vertices |
| faces (Tensor): [T, 3] triangular face indices""" |
| utils3d.torch.mesh.remove_isolated_pieces |
|
|
| @overload |
| def merge_duplicate_vertices(vertices: torch_.Tensor, faces: torch_.Tensor, tol: float = 1e-06) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Merge duplicate vertices of a triangular mesh. |
| Duplicate vertices are merged by selecte one of them, and the face indices are updated accordingly. |
| |
| ## Parameters |
| vertices (Tensor): [N, 3] 3-dimensional vertices |
| faces (Tensor): [T, 3] triangular face indices |
| tol (float, optional): tolerance for merging. Defaults to 1e-6. |
| |
| ## Returns |
| vertices (Tensor): [N_, 3] 3-dimensional vertices |
| faces (Tensor): [T, 3] triangular face indices""" |
| utils3d.torch.mesh.merge_duplicate_vertices |
|
|
| @overload |
| def subdivide_mesh(vertices: torch_.Tensor, faces: torch_.Tensor, n: int = 1) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Subdivide a triangular mesh by splitting each triangle into 4 smaller triangles. |
| NOTE: All original vertices are kept, and new vertices are appended to the end of the vertex list. |
| |
| ## Parameters |
| vertices (Tensor): [N, 3] 3-dimensional vertices |
| faces (Tensor): [T, 3] triangular face indices |
| n (int, optional): number of subdivisions. Defaults to 1. |
| |
| ## Returns |
| vertices (Tensor): [N_, 3] subdivided 3-dimensional vertices |
| faces (Tensor): [4 * T, 3] subdivided triangular face indices""" |
| utils3d.torch.mesh.subdivide_mesh |
|
|
| @overload |
| def compute_mesh_laplacian(vertices: torch_.Tensor, faces: torch_.Tensor, weight: str = 'uniform') -> torch_.Tensor: |
| """Laplacian smooth with cotangent weights |
| |
| ## Parameters |
| vertices (Tensor): shape (..., N, 3) |
| faces (Tensor): shape (T, 3) |
| weight (str): 'uniform' or 'cotangent'""" |
| utils3d.torch.mesh.compute_mesh_laplacian |
|
|
| @overload |
| def laplacian_smooth_mesh(vertices: torch_.Tensor, faces: torch_.Tensor, weight: str = 'uniform', times: int = 5) -> torch_.Tensor: |
| """Laplacian smooth with cotangent weights |
| |
| ## Parameters |
| vertices (Tensor): shape (..., N, 3) |
| faces (Tensor): shape (T, 3) |
| weight (str): 'uniform' or 'cotangent'""" |
| utils3d.torch.mesh.laplacian_smooth_mesh |
|
|
| @overload |
| def taubin_smooth_mesh(vertices: torch_.Tensor, faces: torch_.Tensor, lambda_: float = 0.5, mu_: float = -0.51) -> torch_.Tensor: |
| """Taubin smooth mesh |
| |
| ## Parameters |
| vertices (Tensor): _description_ |
| faces (Tensor): _description_ |
| lambda_ (float, optional): _description_. Defaults to 0.5. |
| mu_ (float, optional): _description_. Defaults to -0.51. |
| |
| ## Returns |
| Tensor: _description_""" |
| utils3d.torch.mesh.taubin_smooth_mesh |
|
|
| @overload |
| def laplacian_hc_smooth_mesh(vertices: torch_.Tensor, faces: torch_.Tensor, times: int = 5, alpha: float = 0.5, beta: float = 0.5, weight: str = 'uniform'): |
| """HC algorithm from Improved Laplacian Smoothing of Noisy Surface Meshes by J.Vollmer et al. |
| """ |
| utils3d.torch.mesh.laplacian_hc_smooth_mesh |
|
|
| @overload |
| def create_cube_mesh(tri: bool = False, device: Optional[torch_.device] = None) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Create a cube mesh of size 1 centered at origin. |
| |
| ### Parameters |
| tri (bool, optional): return triangulated mesh. Defaults to False, which returns quad mesh. |
| |
| ### Returns |
| vertices (Tensor): shape (8, 3) float32 |
| faces (Tensor): shape (12, 3) int32""" |
| utils3d.torch.mesh.create_cube_mesh |
|
|
| @overload |
| def create_camera_frustum_mesh(extrinsics: torch_.Tensor, intrinsics: torch_.Tensor, depth: float = 1.0) -> Tuple[torch_.Tensor, torch_.Tensor, torch_.Tensor]: |
| """Create a triangle mesh of camera frustum.""" |
| utils3d.torch.mesh.create_camera_frustum_mesh |
|
|
| @overload |
| def create_icosahedron_mesh(device: Optional[torch_.device] = None) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Create an icosahedron mesh of centered at origin.""" |
| utils3d.torch.mesh.create_icosahedron_mesh |
|
|
| @overload |
| def uv_map(*size: Union[int, Tuple[int, int]], top: float = 0.0, left: float = 0.0, bottom: float = 1.0, right: float = 1.0, dtype: torch_.dtype = torch_.float32, device: torch_.device = None) -> torch_.Tensor: |
| """Get image UV coordinate map. By default, (0., 0.) is the top-left corner of the image, and (1., 1.) is the bottom-right corner of the image. |
| |
| ## Parameters |
| - `*size`: `Tuple[int, int]` or two integers of map size `(height, width)` |
| - `top`: `float` defaults to 0. |
| - `left`: `float` defaults to 0. |
| - `bottom`: `float` defaults to 1. |
| - `right`: `float` defaults to 1. |
| - `dtype`: `torch.dtype` data type of the output uv map. Defaults to torch.float32. |
| - `device`: `torch.device`, device of the output uv map. Defaults to None. |
| |
| ## Returns |
| - `uv (Tensor)`: shape `(height, width, 2)` |
| |
| ## Example Usage |
| |
| >>> uv_map(10, 10): |
| [[[0.05, 0.05], [0.15, 0.05], ..., [0.95, 0.05]], |
| [[0.05, 0.15], [0.15, 0.15], ..., [0.95, 0.15]], |
| ... ... ... |
| [[0.05, 0.95], [0.15, 0.95], ..., [0.95, 0.95]]]""" |
| utils3d.torch.maps.uv_map |
|
|
| @overload |
| def pixel_coord_map(*size: Union[int, Tuple[int, int]], top: int = 0, left: int = 0, convention: Literal['integer-center', 'integer-corner'] = 'integer-center', dtype: torch_.dtype = torch_.float32, device: torch_.device = None) -> torch_.Tensor: |
| """Get image pixel coordinates map. Support two conventions: `'integer-center'` and `'integer-corner'`. |
| |
| ## Parameters |
| - `*size`: `Tuple[int, int]` or two integers of map size `(height, width)` |
| - `top`: `int`, optional top boundary of the pixel coord map. Defaults to 0. |
| - `left`: `int`, optional left boundary of the pixel coord map. Defaults to 0. |
| - `convention`: `str`, optional `'integer-center'` or `'integer-corner'`, whether integer coordinates correspond to pixel centers or corners. Defaults to 'integer-center'. |
| - `'integer-center'`: `pixel[i][j]` has integer coordinates `(j, i)` as its center, and occupies square area `[j - 0.5, j + 0.5) × [i - 0.5, i + 0.5)`. |
| The top-left corner of the top-left pixel is `(-0.5, -0.5)`, and the bottom-right corner of the bottom-right pixel is `(width - 0.5, height - 0.5)`. |
| - `'integer-corner'`: `pixel[i][j]` has coordinates `(j + 0.5, i + 0.5)` as its center, and occupies square area `[j, j + 1) × [i, i + 1)`. |
| The top-left corner of the top-left pixel is `(0, 0)`, and the bottom-right corner of the bottom-right pixel is `(width, height)`. |
| - `dtype`: `torch.dtype`, optional data type of the output pixel coord map. Defaults to torch.float32. |
| |
| ## Returns |
| Tensor: shape (height, width, 2) |
| |
| >>> pixel_coord_map(10, 10, convention='integer-center', dtype=torch.long): |
| [[[0, 0], [1, 0], ..., [9, 0]], |
| [[0, 1], [1, 1], ..., [9, 1]], |
| ... ... ... |
| [[0, 9], [1, 9], ..., [9, 9]]] |
| |
| >>> pixel_coord_map(10, 10, convention='integer-corner', dtype=torch.float32): |
| [[[0.5, 0.5], [1.5, 0.5], ..., [9.5, 0.5]], |
| [[0.5, 1.5], [1.5, 1.5], ..., [9.5, 1.5]], |
| ... ... ... |
| [[0.5, 9.5], [1.5, 9.5], ..., [9.5, 9.5]]]""" |
| utils3d.torch.maps.pixel_coord_map |
|
|
| @overload |
| def screen_coord_map(*size: Union[int, Tuple[int, int]], top: float = 1.0, left: float = 0.0, bottom: float = 0.0, right: float = 1.0, dtype: torch_.dtype = torch_.float32, device: torch_.device = None) -> torch_.Tensor: |
| """Get screen space coordinate map, where (0., 0.) is the bottom-left corner of the image, and (1., 1.) is the top-right corner of the image. |
| This is commonly used in graphics APIs like OpenGL. |
| |
| ## Parameters |
| - `*size`: `Tuple[int, int]` or two integers of map size `(height, width)` |
| - `top`: `float`, optional top boundary in the screen space. Defaults to 1. |
| - `left`: `float`, optional left boundary in the screen space. Defaults to 0. |
| - `bottom`: `float`, optional bottom boundary in the screen space. Defaults to 0. |
| - `right`: `float`, optional right boundary in the screen space. Defaults to 1. |
| - `dtype`: `torch.dtype`, optional data type of the output map. Defaults to torch.float32. |
| |
| ## Returns |
| (Tensor): shape (height, width, 2)""" |
| utils3d.torch.maps.screen_coord_map |
|
|
| @overload |
| def build_mesh_from_map(*maps: torch_.Tensor, mask: Optional[torch_.Tensor] = None, tri: bool = False) -> Tuple[torch_.Tensor, ...]: |
| """Get a mesh regarding image pixel uv coordinates as vertices and image grid as faces. |
| |
| ## Parameters |
| *maps (Tensor): attribute maps in shape (height, width, [channels]) |
| mask (Tensor, optional): binary mask of shape (height, width), dtype=bool. Defaults to None. |
| |
| ## Returns |
| faces (Tensor): faces connecting neighboring pixels. shape (T, 4) if tri is False, else (T, 3) |
| *attributes (Tensor): vertex attributes in corresponding order with itorchut maps |
| indices (Tensor, optional): indices of vertices in the original mesh""" |
| utils3d.torch.maps.build_mesh_from_map |
|
|
| @overload |
| def build_mesh_from_depth_map(depth: torch_.Tensor, *other_maps: torch_.Tensor, intrinsics: torch_.Tensor, extrinsics: Optional[torch_.Tensor] = None, atol: Optional[float] = None, rtol: Optional[float] = 0.05, tri: bool = False) -> Tuple[torch_.Tensor, ...]: |
| """Get a mesh by lifting depth map to 3D, while removing depths of large depth difference. |
| |
| ## Parameters |
| depth (Tensor): [H, W] depth map |
| extrinsics (Tensor, optional): [4, 4] extrinsics matrix. Defaults to None. |
| intrinsics (Tensor, optional): [3, 3] intrinsics matrix. Defaults to None. |
| *other_maps (Tensor): [H, W, C] vertex attributes. Defaults to None. |
| atol (float, optional): absolute tolerance. Defaults to None. |
| rtol (float, optional): relative tolerance. Defaults to None. |
| triangles with vertices having depth difference larger than atol + rtol * depth will be marked. |
| remove_by_depth (bool, optional): whether to remove triangles with large depth difference. Defaults to True. |
| return_uv (bool, optional): whether to return uv coordinates. Defaults to False. |
| return_indices (bool, optional): whether to return indices of vertices in the original mesh. Defaults to False. |
| |
| ## Returns |
| faces (Tensor): [T, 3] faces |
| vertices (Tensor): [N, 3] vertices |
| *other_attrs (Tensor): [N, C] vertex attributes""" |
| utils3d.torch.maps.build_mesh_from_depth_map |
|
|
| @overload |
| def depth_map_edge(depth: torch_.Tensor, atol: float = None, rtol: float = None, kernel_size: int = 3, mask: torch_.Tensor = None) -> torch_.BoolTensor: |
| """Compute the edge mask of a depth map. The edge is defined as the pixels whose neighbors have a large difference in depth. |
| |
| ## Parameters |
| depth (Tensor): shape (..., height, width), linear depth map |
| atol (float): absolute tolerance |
| rtol (float): relative tolerance |
| |
| ## Returns |
| edge (Tensor): shape (..., height, width) of dtype torch.bool""" |
| utils3d.torch.maps.depth_map_edge |
|
|
| @overload |
| def depth_map_aliasing(depth: torch_.Tensor, atol: float = None, rtol: float = None, kernel_size: int = 3, mask: torch_.Tensor = None) -> torch_.BoolTensor: |
| """Compute the map that indicates the aliasing of a depth map. The aliasing is defined as the pixels which neither close to the maximum nor the minimum of its neighbors. |
| ## Parameters |
| depth (Tensor): shape (..., height, width), linear depth map |
| atol (float): absolute tolerance |
| rtol (float): relative tolerance |
| |
| ## Returns |
| edge (Tensor): shape (..., height, width) of dtype torch.bool""" |
| utils3d.torch.maps.depth_map_aliasing |
|
|
| @overload |
| def point_map_to_normal_map(point: torch_.Tensor, mask: torch_.Tensor = None) -> torch_.Tensor: |
| """Calculate normal map from point map. Value range is [-1, 1]. |
| |
| ## Parameters |
| point (Tensor): shape (..., height, width, 3), point map |
| mask (Tensor): shape (..., height, width), binary mask. Defaults to None. |
| |
| ## Returns |
| normal (Tensor): shape (..., height, width, 3), normal map. """ |
| utils3d.torch.maps.point_map_to_normal_map |
|
|
| @overload |
| def depth_map_to_point_map(depth: torch_.Tensor, intrinsics: torch_.Tensor, extrinsics: torch_.Tensor = None): |
| utils3d.torch.maps.depth_map_to_point_map |
|
|
| @overload |
| def depth_map_to_normal_map(depth: torch_.Tensor, intrinsics: torch_.Tensor, mask: torch_.Tensor = None) -> torch_.Tensor: |
| """Calculate normal map from depth map. Value range is [-1, 1]. Normal direction in OpenCV identity camera's coordinate system. |
| |
| ## Parameters |
| depth (Tensor): shape (..., height, width), linear depth map |
| intrinsics (Tensor): shape (..., 3, 3), intrinsics matrix |
| ## Returns |
| normal (Tensor): shape (..., height, width, 3), normal map. """ |
| utils3d.torch.maps.depth_map_to_normal_map |
|
|
| @overload |
| def chessboard(*size: Union[int, Tuple[int, int]], grid_size: int, color_a: torch_.Tensor, color_b: torch_.Tensor) -> torch_.Tensor: |
| """Get a chessboard image |
| |
| ## Parameters |
| - `*size`: `Tuple[int, int]` or two integers of map size `(height, width)` |
| - `grid_size`: `int`, size of chessboard grid |
| - `color_a`: `Tensor`, shape (channels,), color of the grid at the top-left corner |
| - `color_b`: `Tensor`, shape (channels,), color in complementary grids |
| |
| ## Returns |
| - `image` (Tensor): shape (height, width, channels), chessboard image""" |
| utils3d.torch.maps.chessboard |
|
|
| @overload |
| def bounding_rect_from_mask(mask: torch_.BoolTensor): |
| """Get bounding rectangle of a mask |
| |
| ## Parameters |
| mask (Tensor): shape (..., height, width), mask |
| |
| ## Returns |
| rect (Tensor): shape (..., 4), bounding rectangle (left, top, right, bottom)""" |
| utils3d.torch.maps.bounding_rect_from_mask |
|
|
| @overload |
| def masked_nearest_resize(*image: torch_.Tensor, mask: torch_.Tensor, size: Tuple[int, int], return_index: bool = False) -> Tuple[Unpack[Tuple[torch_.Tensor, ...]], torch_.Tensor, Tuple[torch_.Tensor, ...]]: |
| """Resize image(s) by nearest sampling with mask awareness. Suitable for sparse maps.  |
| - Downsampling: Assign the nearest valid pixel within the target pixel's receptive field. |
| - Upsampling: Assign the valid pixel to only the nearest pixel in the resized map. |
| |
| |
| ### Parameters |
| - `*image`: Itorchut image(s) of shape `(..., H, W, C)` or `(... , H, W)` |
| - You can pass multiple images to be resized at the same time for efficiency. |
| - `mask`: itorchut mask of shape `(..., H, W)`, dtype=bool |
| - `size`: target size `(H', W')` |
| - `return_index`: whether to return the nearest neighbor indices in the original map for each pixel in the resized map. |
| Defaults to False. |
| |
| ### Returns |
| - `*resized_image`: resized image(s) of shape `(..., H', W', C)`. or `(..., H', W')` |
| - `resized_mask`: mask of the resized map of shape `(..., H', W')` |
| - `nearest_indices`: tuple of shape `(..., H', W')`. The nearest neighbor indices of the resized map of each dimension.""" |
| utils3d.torch.maps.masked_nearest_resize |
|
|
| @overload |
| def masked_area_resize(*image: torch_.Tensor, mask: torch_.Tensor, size: Tuple[int, int]) -> Tuple[Unpack[Tuple[torch_.Tensor, ...]], torch_.Tensor]: |
| """Resize 2D map by area sampling with mask awareness. |
| |
| ### Parameters |
| - `*image`: Itorchut image(s) of shape `(..., H, W, C)` or `(..., H, W)` |
| - You can pass multiple images to be resized at the same time for efficiency. |
| - `mask`: Itorchut mask of shape `(..., H, W)` |
| - `size`: target image size `(H', W')` |
| |
| ### Returns |
| - `*resized_image`: resized image(s) of shape `(..., H', W', C)`. or `(..., H', W')` |
| - `resized_mask`: mask of the resized map of shape `(..., H', W')`""" |
| utils3d.torch.maps.masked_area_resize |
|
|
| @overload |
| def flood_fill(*image: torch_.Tensor, mask: torch_.Tensor, return_index: bool = False) -> torch_.Tensor: |
| """Flooding fill the holes in the image(s) according to the mask.  |
| |
| Parameters |
| ---- |
| - `*image` (Tensor): shape (..., height, width, [C]), itorchut image(s) |
| - `mask` (Tensor): shape (..., height, width), binary mask indicating valid regions |
| |
| Returns |
| ---- |
| - `*filled_image` (Tensor): shape (..., height, width, [C]), flood filled map |
| - `filled_indices` (Tuple[Tensor, ...], optional): tuple of shape (..., height, width). The nearest neighbor indices of each pixel in the original map. |
| It satisfies `filled_image = image[filled_indices]`""" |
| utils3d.torch.maps.flood_fill |
|
|
| @overload |
| def perlin_noise(x: torch_.Tensor, seed: Optional[int] = None) -> torch_.Tensor: |
| """Generate Perlin noise for the given coordinates. |
| |
| Parameters |
| ---- |
| - `x` (Tensor): shape (*batch_shape, N_1, ..., N_D, D), coordinates to sample Perlin. |
| If itorchut ndim is more than D + 1, the leading dimensions are treated as batch dimensions. Instances in the batch have different noise patterns. |
| - `seed` (int, optional): random seed. The same seed will generate the same noise pattern(s). Defaults to None. |
| |
| Returns |
| ---- |
| - `y` (Tensor): shape (*batch_shape, N_1, ..., N_D), Perlin noise value at the given coordinates and seed. Value range is approximately [-1, 1]""" |
| utils3d.torch.maps.perlin_noise |
|
|
| @overload |
| def perlin_noise_map(size: Tuple[int, ...], frequency: Union[float, torch_.Tensor], seed: Optional[int] = None, dtype: Optional[torch_.dtype] = None, device: Optional[torch_.device] = None) -> torch_.Tensor: |
| """Generate Perlin noise map. |
| |
| Parameters |
| ---- |
| - `size` (Tuple[int, ...]): size of the noise map (..., H, W) |
| - `frequency` (float | Tensor): frequency relative to map's larger dimension max(H, W) of the Perlin noise. |
| Represents how many periods of noise fit in the larger dimension of the map. |
| - `seed` (int, optional): random seed. The same seed will generate the same noise pattern(s). Defaults to None. |
| |
| Returns |
| ---- |
| - `noise_map` (Tensor): shape (..., H, W), Perlin noise map. Value range is approximately [-1, 1]""" |
| utils3d.torch.maps.perlin_noise_map |
|
|
| @overload |
| def fractal_perlin_noise_map(size: Tuple[int, ...], base_frequency: Union[float, torch_.Tensor], octaves: int = 4, lacunarity: float = 2.0, gain: float = 0.5, seed: Optional[int] = None, dtype: Optional[torch_.dtype] = None, device: Optional[torch_.device] = None) -> torch_.Tensor: |
| """Generate fractal Perlin noise map.  |
| |
| Parameters |
| ---- |
| - `size` (Tuple[int, ...]): size of the noise map (..., H, W) |
| - `base_frequency` (float | Tensor): base frequency (relative to map's larger dimension max(H, W)) of the Perlin noise. |
| Represents how many periods of noise fit in the larger dimension of the map. |
| - `octaves` (int, optional): number of octaves. Defaults to 4. |
| - `lacunarity` (float, optional): frequency multiplier between octaves. Defaults to 2.0. |
| - `gain` (float, optional): amplitude multiplier between octaves. Defaults to 0.5. |
| - `seed` (int, optional): random seed. The same seed will generate the same noise pattern. Defaults to None. |
| |
| Returns |
| ---- |
| - `noise_map` (Tensor): shape (..., H, W), fractal Perlin noise map. Value range is approximately [-1, 1]""" |
| utils3d.torch.maps.fractal_perlin_noise_map |
|
|
| @overload |
| def RastContext(nvd_ctx: Union[nvdiffrast.torch.ops.RasterizeCudaContext, nvdiffrast.torch.ops.RasterizeGLContext] = None, *, backend: Literal['cuda', 'gl'] = 'cuda', device: Union[str, torch_.device] = None): |
| """Create a rasterization context. Nothing but a wrapper of nvdiffrast.torch.RasterizeCudaContext or nvdiffrast.torch.RasterizeGLContext.""" |
| utils3d.torch.rasterization.RastContext |
|
|
| @overload |
| def rasterize_triangles(size: Tuple[int, int], *, vertices: torch_.Tensor, attributes: Optional[torch_.Tensor] = None, faces: torch_.Tensor, view: torch_.Tensor = None, projection: torch_.Tensor = None, extrinsics: torch_.Tensor = None, intrinsics: torch_.Tensor = None, near: float = 0.01, far: float = inf, return_image_derivatives: bool = False, return_depth: bool = False, return_interpolation: bool = False, antialiasing: bool = False, ctx: Optional[utils3d.torch.rasterization.RastContext] = None) -> Tuple[torch_.Tensor, torch_.Tensor, Optional[torch_.Tensor]]: |
| """Rasterize triangles. |
| |
| Parameters |
| ---- |
| size (Tuple[int, int]): (height, width) of the output image |
| vertices (np.ndarray): (B, N, 2 or 3 or 4) |
| faces (Tensor): (T, 3) |
| attributes (Tensor, optional): (B, N, C) vertex attributes. Defaults to None. |
| texture (Tensor, optional): (B, C, H, W) texture. Defaults to None. |
| view | extrinsics (Tensor, optional): ([B,] 4, 4) view matrix or extrinsics matrix. Provide either one of them. Defaults to identity. |
| projection | intrinsics (Tensor, optional): ([B,] 4, 4) projection matrix or ([B,] 3, 3) intrinsics matrix. Provide either one of them. Defaults to identity. |
| near (float, optional): near plane. Defaults to 0.01. Only used for intrinsics. Ignored if projection matrix is provided. |
| far (float, optional): far plane. Defaults to inf. Only used for intrinsics. Ignored if projection matrix is provided. |
| return_image_derivatives (bool, optional): whether to return screen space derivatives of the attributes. Defaults to False. |
| return_depth (bool, optional): whether to return depth map. Defaults to False. |
| return_interpolation (bool, optional): whether to return triangle interpolation maps. Defaults to False. |
| antialiasing (Union[bool, List[int]], optional): whether to perform antialiasing. Defaults to True. If a list of indices is provided, only those channels will be antialiased. |
| ctx (RastContext): rasterization context. Defaults to the thread-local default context. If custom context is needed, provide one with utils3d.pt.RastContext(). |
| |
| Returns |
| ---- |
| A dictionary containing: |
| - image: (Tensor): (B, H, W, C) |
| - image_dr: (Tensor): (B, H, W, C * 2) screen space derivatives of the attributes |
| - depth: (Tensor): (B, H, W) Linear depth. Empty pixels have depth inf. |
| - mask: (torch.BoolTensor): (B, H, W) mask of valid pixels |
| - interpolation_id: (Tensor): (B, H, W) triangle ID map. For empty pixels, the value is -1. |
| - interpolation_uv: (Tensor): (B, H, W, 2) triangle UV (first two channels of barycentric coordinates)""" |
| utils3d.torch.rasterization.rasterize_triangles |
|
|
| @overload |
| def rasterize_triangles_peeling(size: Tuple[int, int], *, vertices: torch_.Tensor, attributes: Optional[torch_.Tensor] = None, faces: torch_.Tensor, view: torch_.Tensor = None, projection: torch_.Tensor = None, extrinsics: torch_.Tensor = None, intrinsics: torch_.Tensor = None, near: float = 0.01, far: float = inf, return_image_derivatives: bool = False, return_depth: bool = False, return_interpolation: bool = False, antialiasing: bool = False, ctx: Optional[utils3d.torch.rasterization.RastContext] = None) -> Iterator[Iterator[Dict[str, torch_.Tensor]]]: |
| """Rasterize a mesh with vertex attributes using depth peeling. |
| |
| Parameters |
| ---- |
| size (Tuple[int, int]): (height, width) of the output image |
| vertices (np.ndarray): (B, N, 2 or 3 or 4) |
| faces (Tensor): (T, 3) |
| attributes (Tensor, optional): (B, N, C) vertex attributes. Defaults to None. |
| texture (Tensor, optional): (B, C, H, W) texture. Defaults to None. |
| view | extrinsics (Tensor, optional): ([B,] 4, 4) view matrix or extrinsics matrix. Provide either one of them. Defaults to identity. |
| projection | intrinsics (Tensor, optional): ([B,] 4, 4) projection matrix or ([B,] 3, 3) intrinsics matrix. Provide either one of them. Defaults to identity. |
| near (float, optional): near plane. Defaults to 0.01. Only used for intrinsics. Ignored if projection matrix is provided. |
| far (float, optional): far plane. Defaults to inf. Only used for intrinsics. Ignored if projection matrix is provided. |
| return_image_derivatives (bool, optional): whether to return screen space derivatives of the attributes. Defaults to False. |
| return_depth (bool, optional): whether to return depth map. Defaults to False. |
| return_interpolation (bool, optional): whether to return triangle interpolation maps. Defaults to False. |
| antialiasing (Union[bool, List[int]], optional): whether to perform antialiasing. Defaults to True. If a list of indices is provided, only those channels will be antialiased. |
| ctx (RastContext): rasterization context. Defaults to the thread-local default context. If custom context is needed, provide one with utils3d.pt.RastContext(). |
| |
| Returns |
| ---- |
| A generator of dictionaries for each layer containing: |
| - mask: (List[torch.BoolTensor]): (B, H, W) mask of valid pixels in this layer |
| - image: (List[Tensor]): (B, C, H, W) rendered images |
| - image_dr: (List[Tensor]): (B, *, H, W) screen space derivatives of the attributes |
| - depth: (List[Tensor]): (B, H, W) linear depth. Empty pixels have depth inf. |
| - interpolation_id: (List[Tensor]): (B, H, W) triangle ID map. For empty pixels, the value is -1. |
| - interpolation_uv: (List[Tensor]): (B, H, W, 2) triangle UV (first two channels of barycentric coordinates) |
| |
| The last layer yielded will be empty, then the generator will stop. |
| |
| Example |
| ---- |
| ``` |
| for i, layer_output in enumerate(rasterize_triangles_peeling( |
| (512, 512), |
| vertices=vertices, |
| faces=faces, |
| attributes=attributes, |
| view=view, |
| projection=projection |
| )): |
| print(f"Layer {i}:") |
| for key, value in layer_output.items(): |
| print(f" {key}: {value.shape}") |
| if i >= 4: # Stop after 5 layers at most |
| break |
| ```""" |
| utils3d.torch.rasterization.rasterize_triangles_peeling |
|
|
| @overload |
| def sample_texture(texture: torch_.Tensor, uv: torch_.Tensor, uv_dr: torch_.Tensor) -> torch_.Tensor: |
| """Interpolate texture using uv coordinates. |
| |
| ## Parameters |
| texture (Tensor): (B, H, W, C) texture |
| uv (Tensor): (B, H, W, 2) uv coordinates |
| uv_dr (Tensor): (B, H, W, 4) uv derivatives |
| |
| ## Returns |
| Tensor: (B, H, W, C) interpolated texture""" |
| utils3d.torch.rasterization.sample_texture |
|
|
| @overload |
| def texture_composite(texture: torch_.Tensor, uv: List[torch_.Tensor], uv_da: List[torch_.Tensor], background: torch_.Tensor = None) -> Tuple[torch_.Tensor, torch_.Tensor]: |
| """Composite textures with depth peeling output. |
| |
| ## Parameters |
| texture (Tensor): (B, C+1, H, W) texture |
| NOTE: the last channel is alpha channel |
| uv (List[Tensor]): list of (B, H, W, 2) uv coordinates |
| uv_da (List[Tensor]): list of (B, H, W, 4) uv derivatives |
| background (Optional[Tensor], optional): (B, C, H, W) background image. Defaults to None (black). |
| |
| ## Returns |
| image: (Tensor): (B, C, H, W) rendered image |
| alpha: (Tensor): (B, H, W) alpha channel""" |
| utils3d.torch.rasterization.texture_composite |
|
|
|
|
