mirror of
https://github.com/ConsistentlyInconsistentYT/Pixeltovoxelprojector.git
synced 2025-10-13 12:22:05 +00:00
b02a5b4f46
This "projectifies" the code as it stood. We add a more detailed README, a Makefile and include the dependencies in source control in a sub directory. Building is updated slightly to output to a `build` directory so we can gitignore artifacts. AI Disclosure: Some copilot use for drafts of the makefile and readme
72 lines
2.1 KiB
Markdown
72 lines
2.1 KiB
Markdown
# Pixeltovoxelprojector
|
|
|
|
Projects motion of pixels to a voxel
|
|
|
|
## Overview
|
|
|
|
PixelToVoxelProjector reconstructs 3D motion or object trajectories from multi-camera image sequences using voxel-based ray accumulation. It provides both C++ and Python tools for processing images, detecting motion, casting rays into a 3D voxel grid, and visualizing results.
|
|
|
|
## Features
|
|
|
|
1. Multi-camera motion detection: Detects moving pixels between consecutive frames for each camera.
|
|
1. Ray casting: Projects rays from camera pixels into a shared 3D voxel grid using voxel DDA.
|
|
1. Voxel accumulation: Aggregates brightness/motion evidence in a 3D grid.
|
|
1. Flexible metadata: Camera parameters and image info are loaded from a JSON file.
|
|
1. Python visualization: Visualizes the reconstructed 3D scene, camera positions, and motion using matplotlib and pyvista.
|
|
1. Astro support: Includes tools for processing astronomical FITS images and mapping sky coordinates.
|
|
|
|
## Requirements
|
|
1. C++17 compiler
|
|
1. Python 3.8+
|
|
|
|
## Example Workflow
|
|
1. Prepare metadata.json and images in a folder.
|
|
1. Run the C++ pipeline to generate voxel_grid.bin.
|
|
1. Use Python scripts to visualize and analyze the voxel grid.
|
|
|
|
|
|
## File Structure and metadata format
|
|
|
|
See [docs](./docs/file_structure.md).
|
|
|
|
## Build Instructions
|
|
C++ Executable
|
|
```bash
|
|
make
|
|
```
|
|
This builds `ray_voxel`.
|
|
|
|
Python Extension (`process_image_cpp`)
|
|
```bash
|
|
# Optionally create a virtual env (recommended)
|
|
python3 -m venv .venv
|
|
# or with uv:
|
|
# uv venv
|
|
# Then activate with (linux)
|
|
source .venv/bin/activate
|
|
# Windows
|
|
# .venv/bin/activate.bat or .venv/bin/Activate.ps1
|
|
|
|
# Install the dependencies
|
|
pip install pybind11 setuptools
|
|
python setup.py build_ext --inplace
|
|
```
|
|
This builds the `process_image_cpp` Python module.
|
|
|
|
## Usage
|
|
C++ Pipeline
|
|
```bash
|
|
./build/ray_voxel metadata.json images_folder output_voxel_grid.bin
|
|
```
|
|
- Processes images and metadata, outputs a binary voxel grid.
|
|
|
|
Python Visualization
|
|
```bash
|
|
python spacevoxelviewer.py
|
|
```
|
|
- Processes FITS images, accumulates into a voxel grid, and visualizes results.
|
|
|
|
```bash
|
|
python voxelmotionviewer.py
|
|
```
|
|
- Loads and interactively visualizes a voxel grid.
|