Arminshfard/neurogs_v2

NeuroGS v2 - 3D Gaussian Splatting for Neuron Reconstruction

This repository contains trained 3D Gaussian Splatting models, checkpoints, and MIP (Maximum Intensity Projection) renderings for neuron reconstruction from microscopy data.

📦 Contents

Checkpoints (103 MB)

• 160+ training checkpoints saved at various iterations (1 to 50,000)
• Final checkpoint: checkpoints/neurogs_codec_ckpt_final.pt (20,450 Gaussians)
• Format: PyTorch .pt files containing Gaussian parameters (positions, scales, rotations, opacities, features)

MIP Projections (5.3 MB)

Ground-truth Maximum Intensity Projections from the original neuron volume:

• 300 views at 256×256 resolution with uniform sphere distribution (Fibonacci lattice)
• Proper aspect ratio preservation with letterboxing
• camera_parameters.json: Full camera metadata (eye position, view matrix, azimuth, elevation, radius)

3DGS Projections - Ray-Based (4.1 MB)

Synthetic MIP projections generated by directly querying the trained 3D Gaussian model:

• 300 views matching Fibonacci sphere camera distribution
• Ray-based rendering: sample 3D points along rays, query Gaussian model, compute max intensity
• camera_parameters.json: Same metadata format

3DGS Projections - Matched Poses (4.2 MB)

Synthetic MIP projections using ground-truth camera poses:

• 300 views with exact camera parameters from mip_projections/camera_parameters.json
• Enables direct comparison between ground-truth volume and 3DGS reconstruction

Volume Data (40 KB)

• 10-2900-control-cell-05_cropped_corrected.swc: Neuron morphology file
• Volume shape: (100, 647, 813) voxels (Z, Y, X)
• Voxel spacing: (1.0, 0.126, 0.126) μm

🔬 Technical Details

3D Gaussian Splatting Model

• 20,450 Gaussians representing the neuron structure
• Trained for 50,000 iterations
• Codec-compressed representation for efficient storage
• Each Gaussian has: 3D position, 3D scale, rotation (quaternion), opacity, appearance features

Camera Configuration

• Uniform sphere sampling: Fibonacci lattice for even distribution
• Camera radius: 1.5 × volume half-diagonal
• Field of view: 50° (default)
• Output resolution: 256×256 pixels (letterboxed to preserve aspect ratio)
• Coordinate system: Camera looks at volume center, up vector aligned with Z-axis

MIP Rendering Methods

1. Ground-truth: Volume rotation + max projection (CUDA-accelerated)
2. Ray-based 3DGS: Direct Gaussian model querying along rays
3. MIP Splatting: 2D Gaussian projection (future implementation)

📊 Dataset Statistics

Component	Count	Total Size	Format
Checkpoints	162 files	103 MB	.pt
GT MIP Images	300 views	5.3 MB	.png
3DGS Ray Images	300 views	4.1 MB	.png
3DGS Matched Images	300 views	4.2 MB	.png
Camera Metadata	3 files	~300 KB	.json
Volume Data	1 file	40 KB	.swc

🚀 Usage

Load Checkpoint

import torch
from model import GaussianMixtureVolume

checkpoint = torch.load('checkpoints/neurogs_codec_ckpt_final.pt')
model = GaussianMixtureVolume(...)
model.load_state_dict(checkpoint, strict=False)

Load Camera Parameters

import json

with open('mip_projections/camera_parameters.json', 'r') as f:
    cameras = json.load(f)

# Access camera for view 0
cam = cameras[0]
eye_pos = cam['eye']               # [x, y, z]
view_matrix = cam['view_matrix_4x4']  # 4×4 matrix
azimuth = cam['azimuth_deg']       # degrees
elevation = cam['elevation_deg']   # degrees

Render MIP from 3DGS Model

See notebook/render_3dgs_mip.ipynb for complete examples:

• Ray-based rendering
• MIP splatting (2D projection)
• Camera pose matching
• Batch processing

📝 Camera Parameters Schema

Each JSON entry contains:

{
  "eye": [x, y, z],                    // Camera position in world space
  "target": [x, y, z],                  // Look-at point (volume center)
  "view_matrix_4x4": [[...], ...],      // 4×4 view transformation matrix
  "azimuth_deg": 0.0,                   // Azimuth angle (0-360°)
  "elevation_deg": 26.57,               // Elevation angle (-90 to 90°)
  "sphere_point": [x, y, z],            // Normalized direction on unit sphere
  "camera_radius": 1234.56,             // Distance from volume center
  "volume_shape_ZYX": [100, 647, 813],  // Original volume dimensions
  "mip_shape_HW": [256, 256],           // Output image size
  "projection_type": "MIP",             // Rendering method
  "rendering_method": "..."             // Specific algorithm used
}

🔗 Related Files

For the complete training pipeline and rendering scripts, see the main repository:

• render_mip_projections.py: Generate ground-truth MIPs
• notebook/render_3dgs_mip.ipynb: 3DGS synthesis notebook
• model.py: GaussianMixtureVolume implementation
• train.py: Training loop

📄 License

This dataset is released for research purposes. Please cite the NeuroGS paper if you use this data in your research.

🙏 Acknowledgments

• Built on 3D Gaussian Splatting
• Neuron data from microscopy imaging
• Fibonacci sphere sampling for uniform camera distribution

📧 Contact

For questions or issues, please open an issue in the repository.

---

Total Dataset Size: ~117 MB
Upload Date: February 13, 2026
Model Version: v2
Training Iterations: 50,000