Formalise project

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

.gitignore

@@ -0,0 +1,2 @@
+build/**
+.venv

Makefile

@@ -0,0 +1,19 @@
+CPPFLAGS =
+CFLAGS = -Wall -W -std=c++17 -O3
+LDFLAGS =
+
+BINDIR = build
+
+all: $(BINDIR)/ray_voxel
+
+$(BINDIR)/ray_voxel: ray_voxel.cpp | $(BINDIR)
+	$(CXX) $(CPPFLAGS) $(CFLAGS) ray_voxel.cpp -o $(BINDIR)/ray_voxel
+
+$(BINDIR):
+	mkdir -p $(BINDIR)
+
+example: $(BINDIR)/ray_voxel
+	./build/ray_voxel motionimages/metadata.json motionimages voxel_grid.bin
+
+clean:
+	$(RM) $(BINDIR)/ray_voxel

README.md

@@ -1,2 +1,72 @@
 # 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.

docs/file_structure.md

@@ -0,0 +1,38 @@
+## File Structure
+`ray_voxel.cpp`
+C++ executable for motion detection, ray casting, and voxel grid accumulation from standard images.
+
+`process_image.cpp`
+C++ code (with pybind11) for advanced image processing, including celestial sphere mapping and voxel grid updates. Built as a Python extension.
+
+`setup.py`
+Python build script for compiling process_image.cpp into a Python module.
+
+`Makefile`
+Build script for compiling C++ executables.
+
+`spacevoxelviewer.py`
+Python script for processing FITS images, accumulating into a voxel grid, and visualizing results.
+
+`voxelmotionviewer.py`
+Python script for interactive visualization of voxel grids.
+
+
+## Metadata Format
+The metadata.json file should be a JSON array, with each entry containing:
+
+```JSON
+[
+  {
+    "camera_index": 0,
+    "frame_index": 0,
+    "yaw": 0.0,
+    "pitch": 0.0,
+    "roll": 0.0,
+    "fov_degrees": 60.0,
+    "image_file": "frame_000.png",
+    "camera_position": [0.0, 0.0, 0.0]
+    // Optional: "object_name", "object_location"
+  }
+]
+```

ray_voxel.cpp

@@ -26,7 +26,7 @@
 // External libraries for JSON & image loading
 #include "nlohmann/json.hpp"
 #define STB_IMAGE_IMPLEMENTATION
-#include "stb_image.h"
+#include "stb/stb_image.h"
 
 
 

requirements.txt

@@ -0,0 +1,6 @@
+pybind11
+setuptools
+wheel
+numpy
+matplotlib
+astropy