shape-completion

shape-completion-utils

Shared utility functions and classes used across all shape-completion submodules. Provides I/O, tensor operations, coordinate transforms, camera geometry, logging, configuration helpers, and visualization utilities.

65+ public functions and classes across four modules: utils.py, logging.py, voxelizer.py, and runtime.py.

Installation

# As submodule (required by all other submodules)

Quick Start

from utils import (
    load_mesh, save_mesh,
    to_tensor, to_numpy,
    normalize_mesh,
    setup_logger,
    setup_config,
)

# Load and process mesh
vertices, faces = load_mesh("model.obj")
mesh = trimesh.Trimesh(vertices, faces)
mesh = normalize_mesh(mesh)
save_mesh("normalized.ply", mesh.vertices, mesh.faces)

# Tensor conversions
tensor = to_tensor(numpy_array, device="cuda")
array = to_numpy(tensor)

Architecture

utils/
├── __init__.py              # Re-exports everything from src/
├── src/
│   ├── __init__.py          # Aggregates exports from all modules
│   ├── utils.py             # Core utility functions (63 functions, 1 class)
│   ├── logging.py           # Logger with custom debug levels
│   ├── voxelizer.py         # Voxelizer class (simple, kdtree, open3d backends)
│   └── runtime.py           # Optional dependency checks and warning suppression
└── tests/
    ├── test_utils.py
    └── test_runtime_logging.py

Function Reference

I/O Functions

Function	Description
`load_mesh(path, load_with=)`	Load mesh vertices and faces; auto-falls-back through trimesh, Open3D, PyMeshLab
`save_mesh(path, vertices, faces, colors=, normals=)`	Save mesh to `.obj`, `.ply`, `.off`, or `.stl` with optional vertex colors/normals
`load_from_binary_hdf5(path, file_names, file_dirs=)`	Load `.npy`, `.npz`, mesh, or image data packed inside an HDF5 container
`save_command_and_args_to_file(path, args=)`	Persist the CLI invocation and parsed arguments to a text file

from utils import load_mesh, save_mesh

# Load mesh (auto-detects format, falls back through backends)
vertices, faces = load_mesh("model.obj")
vertices, faces = load_mesh("model.ply", load_with="trimesh")

# Save mesh with vertex colors
save_mesh("output.ply", vertices, faces, colors=vertex_colors)

Tensor and Array Operations

Function	Description
`to_tensor(x, unsqueeze=, device=)`	Convert scalar, list, ndarray, or Tensor to a CUDA/CPU Tensor (recursively handles lists)
`to_numpy(x, squeeze=)`	Convert Tensor to ndarray (handles GPU, detach, squeeze); passes through non-tensors
`to_scalar(x)`	Extract a Python scalar from any 0-d Tensor or ndarray
`unsqueeze_as(tensor, other)`	Unsqueeze trailing dims of `tensor` to match `other`’s ndim
`normalize(val, a=, b=, p_min=, p_max=)`	Min-max normalize to `[a, b]` with optional percentile clipping; works on both Tensor and ndarray
`filter_dict(d, keep=, remove=)`	Filter a dict by whitelisted or blacklisted key sets
`subsample_indices(data, n, replace=)`	Random subsample of `n` indices from `data`, with optional replacement
`binary_from_multi_class(logits, free_label=, occ_label=)`	Convert multi-class logits to binary (free vs. occupied) via log-sum-exp

from utils import to_tensor, to_numpy, normalize

# NumPy -> Tensor (auto-unsqueezes batch dim, moves to CUDA)
tensor = to_tensor(array, device="cuda")

# Tensor -> NumPy (handles GPU tensors automatically)
array = to_numpy(tensor)

# Normalize with percentile clipping
normed = normalize(depth_values, a=0, b=1, p_min=0.01, p_max=0.99)

Coordinate Transforms

Function	Description
`inv_trafo(trafo)`	Invert a `(4,4)` or `(B,4,4)` homogeneous transform; uses `R^T` when rotation is orthonormal, else full inverse
`apply_trafo(points, trafo)`	Apply a `(4,4)` or `(B,4,4)` rigid transform to `(N,3)` or `(B,N,3)` points
`look_at(eye, target, up=)`	Compute a 4x4 camera pose (inverse extrinsic) in OpenGL convention
`convert_coordinates(pts, in_fmt, out_fmt)`	Convert 3D point coordinates between `"opencv"`, `"opengl"`, and `"blender"` conventions
`convert_extrinsic(ext, in_fmt, out_fmt)`	Convert a 4x4 camera extrinsic between coordinate conventions
`pitch_from_trafo(trafo, roll=, degrees=)`	Extract pitch angle (x-axis rotation) from a 4x4 transform, correcting for gimbal lock
`rot_from_euler(axes, upper_hemisphere)`	Random Euler rotation matrix with optional upper-hemisphere constraint

from utils import look_at, apply_trafo, inv_trafo, convert_coordinates
import numpy as np

# Camera look-at matrix (OpenGL convention)
cam_pose = look_at(eye=np.array([0, 0, 2]), target=np.array([0, 0, 0]))

# Transform points from camera to world frame
points_world = apply_trafo(points_cam, inv_trafo(cam_pose))

# Convert between coordinate conventions
points_gl = convert_coordinates(points_cv, "opencv", "opengl")

Supported coordinate conventions:

OpenCV: x-right, y-down, z-forward
OpenGL: x-right, y-up, z-backward
Blender: x-right, y-forward, z-up

Camera and Intrinsic Utilities

Function	Description
`invert_intrinsic(K)`	Analytically invert a 3x3 intrinsic matrix (fast path for zero-skew case)
`adjust_intrinsic(K, width, height, box=, size=)`	Adjust intrinsic matrix after crop and/or resize; supports batched `K`
`draw_camera(intrinsic, extrinsic, width, height, scale=, color=)`	Create Open3D geometry (frustum + axes) for camera visualization

from utils import adjust_intrinsic, draw_camera

# Adjust intrinsic after cropping and resizing
K_new = adjust_intrinsic(K, width=640, height=480, box=(100, 50, 540, 430), size=256)

# Visualize camera frustum
camera_geoms = draw_camera(K, extrinsic_cv, width=640, height=480, scale=0.1)

Depth and Point Cloud Operations

Function	Description
`depth_to_points(depth, intrinsic, depth_scale=, depth_trunc=)`	Unproject a depth map to 3D points; supports both Tensor and ndarray
`points_to_depth(points, intrinsic, width, height)`	Project 3D points to a depth map image
`points_to_uv(points, intrinsic, extrinsic=, width=, height=)`	Project 3D points to pixel coordinates `(u, v)`; optionally returns valid-pixel mask
`depth_to_image(depth, cmap=, a=, b=)`	Convert a depth map to a colormapped PIL Image for visualization

from utils import depth_to_points, points_to_uv, depth_to_image
import numpy as np

# Unproject depth to point cloud
intrinsic = np.array([[500, 0, 320], [0, 500, 240], [0, 0, 1]])
points = depth_to_points(depth_map, intrinsic)

# Project points to image coordinates
u, v, mask = points_to_uv(points, intrinsic, width=640, height=480)

# Visualize depth with turbo colormap
depth_vis = depth_to_image(depth_map, cmap="turbo")

Ray and Frustum Operations

Function	Description
`get_rays(mask, intrinsic, extrinsic, normalize=, num_samples=)`	Generate ray origins and directions for masked pixels (for NeRF-style sampling)
`sample_distances(n_points, near, far, n_steps=, method=, uniform_in_volume=)`	Sample depths along rays (linear or random, with optional volume-uniform cubic CDF)
`is_in_frustum(points, intrinsic, extrinsic, width, height, near=, far=)`	Boolean mask for which points lie inside a camera frustum

from utils import get_rays, sample_distances

# Generate rays from masked pixels
ray_origins, ray_dirs, u, v = get_rays(mask, K, extrinsic, normalize=True)

# Sample distances along rays (uniform in volume)
distances = sample_distances(n_points=1024, near=0.2, far=2.4, n_steps=64, uniform_in_volume=True)

Grid and Voxel Operations

Function	Description
`make_3d_grid(bb_min, bb_max, shape)`	Create a dense 3D query grid as `(N, 3)` Tensor; supports per-axis resolution
`points_to_coordinates(points, max_value=, plane=, intrinsic=)`	Convert 3D points to normalized `[0,1)` coordinates (optionally project to xy/xz/yz/uv)
`coordinates_to_index(coordinates, resolution)`	Convert `[0,1]` coordinates to flat row-major voxel indices
`Voxelizer(resolution=, padding=, method=, bounds=)`	Class for voxelizing point clouds via `simple`, `kdtree`, or `open3d` backends

from utils import make_3d_grid, Voxelizer

# Create query grid for implicit function evaluation
grid = make_3d_grid(bb_min=-0.5, bb_max=0.5, shape=128)  # (128**3, 3)

# Voxelize a point cloud
voxelizer = Voxelizer(resolution=64, bounds=(-0.5, 0.5), method="simple")
occupancy, voxel_indices = voxelizer(points)  # occupancy: (64, 64, 64)
centers = voxelizer.grid_points                # (64**3, 3)

Mesh Operations

Function	Description
`normalize_mesh(mesh, center=, scale=, cube_or_sphere=)`	Normalize a trimesh to unit cube or unit sphere
`get_points(n_views=)`	Generate `n` evenly-distributed points on a unit sphere (Fibonacci spiral)
`generate_random_basis(n_points=, n_dims=, radius=, seed=)`	Sample points uniformly inside a ball

from utils import normalize_mesh, get_points
import trimesh

mesh = trimesh.load("model.obj")
mesh = normalize_mesh(mesh, cube_or_sphere="sphere")

# 100 viewpoints evenly distributed on a sphere
viewpoints = get_points(n_views=100)

Image Utilities

Function	Description
`stack_images(images)`	Stack a list of images into a square grid (auto-computes rows/cols)
`crop_and_resize_image(img, box=, size=, color=, interpolation=)`	Crop to bounding box and/or resize (largest edge to `size`); handles ndarray, PIL, and Tensor
`bbox_from_mask(mask, padding=)`	Compute a square bounding box from a binary mask with optional padding

from utils import stack_images, bbox_from_mask, crop_and_resize_image

# Create 2x2 image grid
grid = stack_images([img1, img2, img3, img4])

# Crop to object region
bbox = bbox_from_mask(segmentation_mask, padding=0.1)
cropped = crop_and_resize_image(image, box=bbox, size=256)

Configuration and Experiment Management

Function	Description
`setup_config(cfg, seed_workers=, functions=)`	Initialize config: detect GPU capabilities, set precision, seed, log level, run validators
`check_cfg(cfg)`	Validate config consistency (point loading, NeRF flags, SDF thresholds, etc.)
`resolve_save_dir(cfg)`	Compute experiment save directory from config (`dirs.log / project / name`)
`resolve_backup_dir(cfg)`	Compute backup directory path
`resolve_weights_path(cfg, weights_path=)`	Search multiple candidate paths for a model weights file
`resolve_checkpoint_path(cfg)`	Search for a checkpoint `.ckpt` file across save/backup dirs
`config_hash(cfg, length=, ignore=)`	Deterministic MD5 hash of config (ignoring runtime/logging keys) for caching
`TrackingDictConfig`	DictConfig subclass that records which keys are accessed (for detecting unused config)

from utils import setup_config, resolve_save_dir, config_hash

cfg = setup_config(cfg)
save_dir = resolve_save_dir(cfg)
run_hash = config_hash(cfg, length=8)  # e.g. "a3f1c02b"

Logging

Symbol	Description
`setup_logger(name)`	Create a `ShapeCompletionLogger` with rank-zero-only output (for distributed training)
`set_log_level(level)`	Set log level on all loggers created via `setup_logger`
`DEBUG_LEVEL_1`, `DEBUG_LEVEL_2`	Custom log levels between `DEBUG` (10) and `INFO` (20): level 12 and 11

from utils import setup_logger, set_log_level

logger = setup_logger(__name__)
logger.info("Training started")
logger.debug_level_1("Detailed debug info")   # Only shown at verbose >= 1
logger.debug_level_2("Very detailed debug")   # Only shown at verbose >= 2

set_log_level("DEBUG")  # Enable all debug output

Path Utilities

Function	Description
`resolve_path(path)`	Expand `~` and resolve to absolute `Path`
`git_show_toplevel(cwd=)`	Get the root of the current git repo
`git_show_superproject_working_tree(cwd=)`	Get the superproject root (for submodules)
`get_git_root()`	Get the top-level project root (superproject if inside a submodule)
`git_submodule_path(name_or_path)`	Resolve a submodule name or file path to its git root
`resolve_out_dir(in_path, in_dir, out_dir, shard=)`	Compute an output path mirroring the input directory structure
`eval_input(inputs, in_format=, recursion_depth=)`	Glob/resolve input file paths; shuffles by default

from utils import git_submodule_path, resolve_path, eval_input

models_path = git_submodule_path("models")
full_path = resolve_path("~/data/meshes")
mesh_files = eval_input(Path("data/"), in_format=".obj", sort=True)

Decorators

Decorator	Description
`@measure_runtime`	Log function execution time; also usable as context manager. Supports custom log levels and CUDA sync.
`@default_on_exception(default, exceptions=)`	Return a default value on exception; logs the error; clears CUDA cache on OOM
`@get_args(print_args=)`	Capture and optionally print function arguments as a dict

from utils import measure_runtime, default_on_exception

@measure_runtime
def train_epoch():
    ...  # Logs: "train_epoch takes 45.2000s"

# Also works as a context manager
with measure_runtime("data loading"):
    load_data()  # Logs: "data loading took 1.2345s"

@default_on_exception(default=[], exceptions=(FileNotFoundError, ValueError))
def load_data(path):
    ...  # Returns [] on FileNotFoundError or ValueError

Hardware and Distributed Utilities

Function	Description
`count_gpus()`	Count available GPUs via `nvidia-smi`
`get_num_workers(n=)`	Auto-determine DataLoader workers (reads `SLURM_CPUS_PER_TASK`; disables multithreading if workers > 1)
`get_device_info()`	Get lowest GPU compute capability; sets float32 matmul precision to `"high"` on capability > 7
`is_distributed()`	Check if running in a distributed (multi-GPU) setup
`disable_multithreading()`	Set `OPENBLAS/MKL/OMP/TBB_NUM_THREADS=1`

from utils import get_num_workers, is_distributed

num_workers = get_num_workers()  # Auto from SLURM or CPU count
if is_distributed():
    ...  # Multi-GPU logic

Runtime and Dependency Management

Function	Description
`suppress_known_optional_dependency_warnings()`	Suppress xFormers and Triton redefinition warnings
`log_optional_dependency_summary(logger, cfg=)`	Log which optional dependencies (xformers, bpy, torch_cluster, etc.) are available vs. needed

Miscellaneous

Function	Description
`cosine_anneal(start, stop, steps, current_step)`	Cosine annealing schedule value
`resolve_dtype(precision, integer=, unsigned=)`	Map numeric precision (8/16/32/64) to NumPy dtype
`monkey_patch(instance, method_name, new_method)`	Replace a method on an object instance at runtime
`stdout_redirected(to=, enabled=)`	Context manager to redirect all stdout (including C-level) to a file or `/dev/null`

from utils import stdout_redirected, cosine_anneal
import os

# Suppress noisy library output
with stdout_redirected(to=os.devnull):
    noisy_library_call()

# Cosine annealing
lr = cosine_anneal(start=1e-3, stop=1e-5, steps=1000, current_step=500)

Constants

from utils import PARTNET_COLORS, PLOTLY_COLORS, DEBUG_LEVEL_1, DEBUG_LEVEL_2

# Color palettes for part segmentation visualization
colors = PARTNET_COLORS  # (50, 3) ndarray, PartNet segmentation colors
colors = PLOTLY_COLORS   # Plotly qualitative Pastel + Pastel1 + Pastel2 + Plotly colors

# Custom debug levels (between DEBUG=10 and INFO=20)
# DEBUG_LEVEL_2 = 11, DEBUG_LEVEL_1 = 12

This site is open source. Improve this page.