utils3d

A collection of useful Python utility functions for 3D computer vision and graphics researchers.

NOTE: This repo is frequently updated and never guarantees backward compatibility.

• If using utils3d as a dependency, please use a commit ID or fork this repo.
• If you find some functions helpful here, consider copying and pasting the functions to your own code.

Install

Install via pip + git

pip install git+https://github.com/EasternJournalist/utils3d.git

or clone the repo and install

git clone https://github.com/EasternJournalist/utils3d.git
pip install ./utils3d

Table of Contents

Transforms

Function	Numpy	Pytorch
utils3d.angle_between Calculate the angle between two vectors.	utils3d.np.angle_between(v1, v2)	utils3d.th.angle_between(v1, v2, eps)
utils3d.axis_angle_to_matrix Convert axis-angle representation (rotation vector) to rotation matrix, whose direction is the axis of rotation and length is the angle of rotation	utils3d.np.axis_angle_to_matrix(axis_angle, eps)	utils3d.th.axis_angle_to_matrix(axis_angle, eps)
utils3d.axis_angle_to_quaternion	-	utils3d.th.axis_angle_to_quaternion(axis_angle, eps)
utils3d.crop_intrinsics Evaluate the new intrinsics(s) after crop the image: cropped_img = img[top:top+crop_height, left:left+crop_width]	utils3d.np.crop_intrinsics(intrinsics, width, height, left, top, crop_width, crop_height)	utils3d.th.crop_intrinsics(intrinsics, original_height, original_width, cropped_left, cropped_top, cropped_height, cropped_width)
utils3d.depth_buffer_to_linear OpenGL depth buffer to linear depth	utils3d.np.depth_buffer_to_linear(depth_buffer, near, far)	utils3d.th.depth_buffer_to_linear(depth, near, far)
utils3d.depth_linear_to_buffer Project linear depth to depth value in screen space	utils3d.np.depth_linear_to_buffer(depth, near, far)	utils3d.th.depth_linear_to_buffer(depth, near, far)
utils3d.euler_angles_to_matrix Convert rotations given as Euler angles in radians to rotation matrices.	utils3d.np.euler_angles_to_matrix(euler_angles, convention)	utils3d.th.euler_angles_to_matrix(euler_angles, convention)
utils3d.euler_axis_angle_rotation Return the rotation matrices for one of the rotations about an axis	utils3d.np.euler_axis_angle_rotation(axis, angle)	utils3d.th.euler_axis_angle_rotation(axis, angle)
utils3d.extrinsics_look_at Get OpenCV extrinsics matrix looking at something	utils3d.np.extrinsics_look_at(eye, look_at, up)	utils3d.th.extrinsics_look_at(eye, look_at, up)
utils3d.extrinsics_to_essential extrinsics matrix [[R, t] [0, 0, 0, 1]] such that x' = R (x - t) to essential matrix such that x' E x = 0	utils3d.np.extrinsics_to_essential(extrinsics)	utils3d.th.extrinsics_to_essential(extrinsics)
utils3d.extrinsics_to_view OpenCV camera extrinsics to OpenGL view matrix	utils3d.np.extrinsics_to_view(extrinsics)	utils3d.th.extrinsics_to_view(extrinsics)
utils3d.focal_to_fov	utils3d.np.focal_to_fov(focal)	utils3d.th.focal_to_fov(focal)
utils3d.fov_to_focal	utils3d.np.fov_to_focal(fov)	utils3d.th.fov_to_focal(fov)
utils3d.interpolate_extrinsics	-	utils3d.th.interpolate_extrinsics(ext1, ext2, t)
utils3d.interpolate_view	-	utils3d.th.interpolate_view(view1, view2, t)
utils3d.intrinsics_from_focal_center Get OpenCV intrinsics matrix	utils3d.np.intrinsics_from_focal_center(fx, fy, cx, cy)	utils3d.th.intrinsics_from_focal_center(fx, fy, cx, cy)
utils3d.intrinsics_from_fov Get normalized OpenCV intrinsics matrix from given field of view.	utils3d.np.intrinsics_from_fov(fov_x, fov_y, fov_max, fov_min, aspect_ratio)	utils3d.th.intrinsics_from_fov(fov_x, fov_y, fov_max, fov_min, aspect_ratio)
utils3d.intrinsics_to_fov	utils3d.np.intrinsics_to_fov(intrinsics)	utils3d.th.intrinsics_to_fov(intrinsics)
utils3d.intrinsics_to_perspective OpenCV intrinsics to OpenGL perspective matrix	utils3d.np.intrinsics_to_perspective(intrinsics, near, far)	utils3d.th.intrinsics_to_perspective(intrinsics, near, far)
utils3d.lerp Linear interpolation between two vectors.	utils3d.np.lerp(x1, x2, t)	-
utils3d.lerp_se3_matrix Linear interpolation between two SE(3) matrices.	utils3d.np.lerp_se3_matrix(T1, T2, t)	-
utils3d.make_se3_matrix Convert rotation matrix and translation vector to 4x4 transformation matrix.	utils3d.np.make_se3_matrix(R, t)	utils3d.th.make_se3_matrix(R, t)
utils3d.matrix_to_axis_angle	-	utils3d.th.matrix_to_axis_angle(rot_mat, eps)
utils3d.matrix_to_euler_angles	-	utils3d.th.matrix_to_euler_angles(matrix, convention)
utils3d.matrix_to_quaternion Convert 3x3 rotation matrix to quaternion (w, x, y, z)	utils3d.np.matrix_to_quaternion(rot_mat, eps)	utils3d.th.matrix_to_quaternion(rot_mat, eps)
utils3d.normalize_intrinsics Normalize intrinsics from pixel cooridnates to uv coordinates	utils3d.np.normalize_intrinsics(intrinsics, width, height, integer_pixel_centers)	utils3d.th.normalize_intrinsics(intrinsics, width, height)
utils3d.perspective_from_fov Get OpenGL perspective matrix from field of view	utils3d.np.perspective_from_fov(fov_x, fov_y, fov_min, fov_max, aspect_ratio, near, far)	utils3d.th.perspective_from_fov(fov_x, fov_y, fov_min, fov_max, aspect_ratio, near, far)
utils3d.perspective_from_window Get OpenGL perspective matrix from the window of z=-1 projection plane	utils3d.np.perspective_from_window(left, right, bottom, top, near, far)	utils3d.th.perspective_from_window(left, right, bottom, top, near, far)
utils3d.perspective_to_intrinsics OpenGL perspective matrix to OpenCV intrinsics	utils3d.np.perspective_to_intrinsics(perspective)	utils3d.th.perspective_to_intrinsics(perspective)
utils3d.perspective_to_near_far Get near and far planes from OpenGL perspective matrix	utils3d.np.perspective_to_near_far(perspective)	-
utils3d.piecewise_lerp Linear spline interpolation.	utils3d.np.piecewise_lerp(x, t, s, extrapolation_mode)	-
utils3d.piecewise_lerp_se3_matrix Linear spline interpolation for SE(3) matrices.	utils3d.np.piecewise_lerp_se3_matrix(T, t, s, extrapolation_mode)	-
utils3d.pixel_to_ndc Convert pixel coordinates to NDC (Normalized Device Coordinates).	utils3d.np.pixel_to_ndc(pixel, width, height, pixel_definition)	utils3d.th.pixel_to_ndc(pixel, width, height, pixel_definition)
utils3d.pixel_to_uv Convert pixel coordiantes to UV coordinates.	utils3d.np.pixel_to_uv(pixel, width, height, pixel_definition)	utils3d.th.pixel_to_uv(pixel, width, height, pixel_definition)
utils3d.project Calculate projection.	utils3d.np.project(points, intrinsics, extrinsics, view, projection)	utils3d.th.project(points, intrinsics, extrinsics, view, projection)
utils3d.project_cv Project 3D points to 2D following the OpenCV convention	utils3d.np.project_cv(points, intrinsics, extrinsics)	utils3d.th.project_cv(points, intrinsics, extrinsics)
utils3d.project_gl Project 3D points to 2D following the OpenGL convention (except for row major matrices)	utils3d.np.project_gl(points, projection, view)	utils3d.th.project_gl(points, projection, view)
utils3d.quaternion_to_axis_angle	-	utils3d.th.quaternion_to_axis_angle(quaternion, eps)
utils3d.quaternion_to_matrix Converts a batch of quaternions (w, x, y, z) to rotation matrices	utils3d.np.quaternion_to_matrix(quaternion, eps)	utils3d.th.quaternion_to_matrix(quaternion, eps)
utils3d.ray_intersection Compute the intersection/closest point of two D-dimensional rays	utils3d.np.ray_intersection(p1, d1, p2, d2)	-
utils3d.rotate_2d	-	utils3d.th.rotate_2d(theta, center)
utils3d.rotation_matrix_2d	-	utils3d.th.rotation_matrix_2d(theta)
utils3d.rotation_matrix_from_vectors Rotation matrix that rotates v1 to v2	utils3d.np.rotation_matrix_from_vectors(v1, v2)	utils3d.th.rotation_matrix_from_vectors(v1, v2)
utils3d.scale_2d	-	utils3d.th.scale_2d(scale, center)
utils3d.screen_coord_to_view_coord Unproject screen space coordinates to 3D view space following the OpenGL convention (except for row major matrices)	utils3d.np.screen_coord_to_view_coord(screen_coord, projection)	-
utils3d.skew_symmetric Skew symmetric matrix from a 3D vector	utils3d.np.skew_symmetric(v)	utils3d.th.skew_symmetric(v)
utils3d.slerp	-	utils3d.th.slerp(rot_mat_1, rot_mat_2, t)
utils3d.slerp_quaternion Spherical linear interpolation between two unit quaternions.	utils3d.np.slerp_quaternion(q1, q2, t)	-
utils3d.slerp_vector Spherical linear interpolation between two unit vectors. The vectors are assumed to be normalized.	utils3d.np.slerp_vector(v1, v2, t)	-
utils3d.transform Apply affine transformation(s) to a point or a set of points.	utils3d.np.transform(x, Ts)	utils3d.th.transform(x, Ts)
utils3d.translate_2d	-	utils3d.th.translate_2d(translation)
utils3d.unproject Calculate inverse projection.	utils3d.np.unproject(uv, depth, intrinsics, extrinsics, projection, view)	utils3d.th.unproject(uv, depth, intrinsics, extrinsics, projection, view)
utils3d.unproject_cv Unproject uv coordinates to 3D view space following the OpenCV convention	utils3d.np.unproject_cv(uv, depth, intrinsics, extrinsics)	utils3d.th.unproject_cv(uv, depth, intrinsics, extrinsics)
utils3d.unproject_gl Unproject screen space coordinates to 3D view space following the OpenGL convention (except for row major matrices)	utils3d.np.unproject_gl(uv, depth, projection, view)	utils3d.th.unproject_gl(uv, depth, projection, view)
utils3d.uv_to_pixel Convert UV coordinates to pixel coordinates.	utils3d.np.uv_to_pixel(uv, width, height, pixel_definition)	utils3d.th.uv_to_pixel(uv, width, height, pixel_definition)
utils3d.view_look_at Get OpenGL view matrix looking at something	utils3d.np.view_look_at(eye, look_at, up)	utils3d.th.view_look_at(eye, look_at, up)
utils3d.view_to_extrinsics OpenGL view matrix to OpenCV camera extrinsics	utils3d.np.view_to_extrinsics(view)	utils3d.th.view_to_extrinsics(view)

Maps

Function	Numpy	Pytorch
utils3d.bounding_rect_from_mask	-	utils3d.th.bounding_rect_from_mask(mask)
utils3d.build_mesh_from_depth_map Get a mesh by lifting depth map to 3D, while removing depths of large depth difference.	utils3d.np.build_mesh_from_depth_map(depth, other_maps, intrinsics, extrinsics, atol, rtol, tri)	utils3d.th.build_mesh_from_depth_map(depth, other_maps, intrinsics, extrinsics, atol, rtol, tri)
utils3d.build_mesh_from_map Get a mesh regarding image pixel uv coordinates as vertices and image grid as faces.	utils3d.np.build_mesh_from_map(maps, mask, tri)	utils3d.th.build_mesh_from_map(maps, mask, tri)
utils3d.chessboard get x chessboard image	utils3d.np.chessboard(height, width, grid_size, color_a, color_b)	utils3d.th.chessboard(width, height, grid_size, color_a, color_b)
utils3d.depth_map_aliasing 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.	utils3d.np.depth_map_aliasing(depth, atol, rtol, kernel_size, mask)	utils3d.th.depth_map_aliasing(depth, atol, rtol, kernel_size, mask)
utils3d.depth_map_edge Compute the edge mask from depth map. The edge is defined as the pixels whose neighbors have large difference in depth.	utils3d.np.depth_map_edge(depth, atol, rtol, kernel_size, mask)	utils3d.th.depth_map_edge(depth, atol, rtol, kernel_size, mask)
utils3d.depth_map_to_normal_map Calculate normal map from depth map. Value range is [-1, 1]. Normal direction in OpenCV identity camera's coordinate system.	utils3d.np.depth_map_to_normal_map(depth, intrinsics, mask, edge_threshold)	utils3d.th.depth_map_to_normal_map(depth, intrinsics, mask)
utils3d.depth_map_to_point_map Unproject depth map to 3D points.	utils3d.np.depth_map_to_point_map(depth, intrinsics, extrinsics)	utils3d.th.depth_map_to_point_map(depth, intrinsics, extrinsics)
utils3d.normal_map_edge Compute the edge mask from normal map.	utils3d.np.normal_map_edge(normals, tol, kernel_size, mask)	-
utils3d.pixel_coord_map 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.	utils3d.np.pixel_coord_map(height, width, left, top, definition, dtype)	utils3d.th.pixel_coord_map(height, width, left, top, definition, dtype, device)
utils3d.point_map_to_normal_map Calculate normal map from point map. Value range is [-1, 1].	utils3d.np.point_map_to_normal_map(point, mask, edge_threshold)	utils3d.th.point_map_to_normal_map(point, mask)
utils3d.screen_coord_map 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.	utils3d.np.screen_coord_map(height, width, left, top, right, bottom, dtype)	-
utils3d.uv_map 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.	utils3d.np.uv_map(height, width, left, top, right, bottom, dtype)	utils3d.th.uv_map(height, width, left, top, right, bottom, dtype, device)

Mesh

Function	Numpy	Pytorch
utils3d.calc_quad_candidates Calculate the candidate quad faces.	utils3d.np.calc_quad_candidates(edges, face2edge, edge2face)	-
utils3d.calc_quad_direction Calculate the direction of each candidate quad face.	utils3d.np.calc_quad_direction(vertices, quads)	-
utils3d.calc_quad_distortion Calculate the distortion of each candidate quad face.	utils3d.np.calc_quad_distortion(vertices, quads)	-
utils3d.calc_quad_smoothness Calculate the smoothness of each candidate quad face connection.	utils3d.np.calc_quad_smoothness(quad2edge, quad2adj, quads_direction)	-
utils3d.camera_frustum Get x triangle mesh of camera frustum.	utils3d.np.camera_frustum(extrinsics, intrinsics, depth)	-
utils3d.compute_boundaries	-	utils3d.th.compute_boundaries(faces, edges, face2edge, edge_degrees)
utils3d.compute_connected_components	-	utils3d.th.compute_connected_components(faces, edges, face2edge)
utils3d.compute_dual_graph	-	utils3d.th.compute_dual_graph(face2edge)
utils3d.compute_edge_connected_components	-	utils3d.th.compute_edge_connected_components(edges)
utils3d.compute_edges	-	utils3d.th.compute_edges(faces)
utils3d.compute_face_corner_angles Compute face corner angles of a mesh	utils3d.np.compute_face_corner_angles(vertices, faces)	utils3d.th.compute_face_corner_angles(vertices, faces)
utils3d.compute_face_corner_normals Compute the face corner normals of a mesh	utils3d.np.compute_face_corner_normals(vertices, faces, normalized)	utils3d.th.compute_face_corner_normals(vertices, faces, normalized)
utils3d.compute_face_normals Compute face normals of a mesh	utils3d.np.compute_face_normals(vertices, faces)	utils3d.th.compute_face_normals(vertices, faces)
utils3d.compute_face_tbn	-	utils3d.th.compute_face_tbn(pos, faces_pos, uv, faces_uv, eps)
utils3d.compute_vertex_normals Compute vertex normals of a triangular mesh by averaging neighboring face normals	utils3d.np.compute_vertex_normals(vertices, faces, weighted)	utils3d.th.compute_vertex_normals(vertices, faces, weighted)
utils3d.compute_vertex_tbn	-	utils3d.th.compute_vertex_tbn(faces_topo, pos, faces_pos, uv, faces_uv)
utils3d.cube Get x cube mesh of size 1 centered at origin.	utils3d.np.cube(tri)	-
utils3d.flatten_mesh_indices	utils3d.np.flatten_mesh_indices(args)	-
utils3d.icosahedron	utils3d.np.icosahedron()	-
utils3d.laplacian	-	utils3d.th.laplacian(vertices, faces, weight)
utils3d.laplacian_hc_smooth_mesh	-	utils3d.th.laplacian_hc_smooth_mesh(vertices, faces, times, alpha, beta, weight)
utils3d.laplacian_smooth_mesh	-	utils3d.th.laplacian_smooth_mesh(vertices, faces, weight, times)
utils3d.merge_duplicate_vertices Merge duplicate vertices of a triangular mesh.	utils3d.np.merge_duplicate_vertices(vertices, faces, tol)	utils3d.th.merge_duplicate_vertices(vertices, faces, tol)
utils3d.merge_meshes Merge multiple meshes into one mesh. Vertices will be no longer shared.	utils3d.np.merge_meshes(meshes)	-
utils3d.mesh_relations Calculate the relation between vertices and faces.	utils3d.np.mesh_relations(faces)	-
utils3d.remove_corrupted_faces Remove corrupted faces (faces with duplicated vertices)	utils3d.np.remove_corrupted_faces(faces)	utils3d.th.remove_corrupted_faces(faces)
utils3d.remove_isolated_pieces	-	utils3d.th.remove_isolated_pieces(vertices, faces, connected_components, thresh_num_faces, thresh_radius, thresh_boundary_ratio, remove_unreferenced)
utils3d.remove_unused_vertices Remove unreferenced vertices of a mesh.	utils3d.np.remove_unused_vertices(faces, vertice_attrs, return_indices)	utils3d.th.remove_unused_vertices(faces, vertice_attrs, return_indices)
utils3d.solve_quad Solve the quad mesh from the candidate quad faces.	utils3d.np.solve_quad(face2edge, edge2face, quad2adj, quads_distortion, quads_smoothness, quads_valid)	-
utils3d.solve_quad_qp Solve the quad mesh from the candidate quad faces.	utils3d.np.solve_quad_qp(face2edge, edge2face, quad2adj, quads_distortion, quads_smoothness, quads_valid)	-
utils3d.square Get a square mesh of area 1 centered at origin in the xy-plane.	utils3d.np.square(tri)	-
utils3d.subdivide_mesh Subdivide a triangular mesh by splitting each triangle into 4 smaller triangles.	utils3d.np.subdivide_mesh(vertices, faces, n)	utils3d.th.subdivide_mesh(vertices, faces, n)
utils3d.taubin_smooth_mesh	-	utils3d.th.taubin_smooth_mesh(vertices, faces, lambda_, mu_)
utils3d.tri_to_quad Convert a triangle mesh to a quad mesh.	utils3d.np.tri_to_quad(vertices, faces)	-
utils3d.triangulate_mesh Triangulate a polygonal mesh.	utils3d.np.triangulate_mesh(faces, vertices, method)	utils3d.th.triangulate_mesh(faces, vertices, method)

Rasterization

Function	Numpy	Pytorch
utils3d.RastContext	utils3d.np.RastContext(args, kwargs)	utils3d.th.RastContext(nvd_ctx, backend, device)
utils3d.rasterize_lines Rasterize lines.	utils3d.np.rasterize_lines(ctx, width, height, vertices, lines, attributes, attributes_domain, view, projection, line_width, return_depth, return_interpolation, background_image, background_depth, background_interpolation_id, background_interpolation_uv)	-
utils3d.rasterize_point_cloud Rasterize point cloud.	utils3d.np.rasterize_point_cloud(ctx, width, height, points, point_sizes, point_size_in, point_shape, attributes, view, projection, return_depth, return_point_id, background_image, background_depth, background_point_id)	-
utils3d.rasterize_triangles Rasterize triangles.	utils3d.np.rasterize_triangles(ctx, width, height, vertices, attributes, attributes_domain, faces, view, projection, cull_backface, return_depth, return_interpolation, background_image, background_depth, background_interpolation_id, background_interpolation_uv)	utils3d.th.rasterize_triangles(ctx, width, height, vertices, faces, attr, uv, texture, model, view, projection, antialiasing, diff_attrs)
utils3d.rasterize_triangles_peeling Rasterize triangles with depth peeling.	utils3d.np.rasterize_triangles_peeling(ctx, width, height, vertices, attributes, attributes_domain, faces, view, projection, cull_backface, return_depth, return_interpolation)	utils3d.th.rasterize_triangles_peeling(ctx, vertices, faces, width, height, max_layers, attr, uv, texture, model, view, projection, antialiasing, diff_attrs)
utils3d.sample_texture Sample from a texture map with a UV map.	utils3d.np.sample_texture(ctx, uv_map, texture_map, interpolation, mipmap_level, repeat, anisotropic)	utils3d.th.sample_texture(texture, uv, uv_da)
utils3d.test_rasterization Test if rasterization works. It will render a cube with random colors and save it as a CHECKME.png file.	utils3d.np.test_rasterization(ctx)	-
utils3d.texture_composite	-	utils3d.th.texture_composite(texture, uv, uv_da, background)
utils3d.warp_image_by_depth	-	utils3d.th.warp_image_by_depth(ctx, depth, image, mask, width, height, extrinsics_src, extrinsics_tgt, intrinsics_src, intrinsics_tgt, near, far, antialiasing, backslash, padding, return_uv, return_dr)
utils3d.warp_image_by_forward_flow	-	utils3d.th.warp_image_by_forward_flow(ctx, image, flow, depth, antialiasing, backslash)

Utils

Function	Numpy	Pytorch
utils3d.lookup Look up query in key like a dictionary.	utils3d.np.lookup(key, query, value, default_value)	utils3d.th.lookup(key, query)
utils3d.masked_max	-	utils3d.th.masked_max(input, mask, dim, keepdim)
utils3d.masked_min	-	utils3d.th.masked_min(input, mask, dim, keepdim)
utils3d.max_pool_1d	utils3d.np.max_pool_1d(x, kernel_size, stride, padding, axis)	-
utils3d.max_pool_2d	utils3d.np.max_pool_2d(x, kernel_size, stride, padding, axis)	-
utils3d.max_pool_nd	utils3d.np.max_pool_nd(x, kernel_size, stride, padding, axis)	-
utils3d.sliding_window	utils3d.np.sliding_window(x, window_size, stride, axis)	utils3d.th.sliding_window(x, window_size, stride, dim)