Metadata-Version: 2.4
Name: synema
Version: 0.1
Summary: View Synthesis for Cinema
Author-email: Li-Ta Lo <ollie@lanl.gov>
License: BSD
Project-URL: Homepage, https://github.com/cinemascience/synema
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: jax<1.0,>=0.5.2
Requires-Dist: flax<1.0,>=0.12.0
Requires-Dist: optax<1.0,>=0.2.7
Requires-Dist: jaxtyping<1.0,>=0.3.0
Requires-Dist: numpy<3.0,>=1.26.4
Requires-Dist: matplotlib<4.0,>=3.10.7
Requires-Dist: h5py<4.0,>=3.15.0
Requires-Dist: tqdm<5.0,>=4.66.4
Provides-Extra: dev
Requires-Dist: build<3.0,>=1.0; extra == "dev"
Requires-Dist: twine<6,>=5; extra == "dev"
Requires-Dist: ruff<1.0,>=0.6; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Provides-Extra: cuda12
Requires-Dist: jax[cuda12]<1.0,>=0.5.2; extra == "cuda12"

# Synema

**Synema** is a collection of neural radiance field (NeRF-style)
view-synthesis utilities designed to work with **Cinema image-based
databases** for in situ / in transit visualization workflows.

The goal is to take an existing Cinema dataset (images + camera
parameters) and enable **novel view synthesis** (new viewpoints, smooth
camera paths, view interpolation) to enhance interactive exploration
without requiring additional simulation output.

------------------------------------------------------------------------

## Backend: JAX / Flax Ecosystem

Synema is implemented using the **JAX ecosystem**, not PyTorch or
TensorFlow.

Core ML stack:

-   **JAX** --- numerical backend (XLA-compiled array computing)
-   **Flax** --- neural network module system
-   **Optax** --- optimizers
-   **Jaxtyping** --- type annotations for JAX arrays

### Why JAX?

-   High-performance XLA compilation
-   Functional programming model well-suited for NeRF training
-   Clean separation between model definition (Flax) and optimization
    (Optax)
-   Excellent support for GPU and TPU acceleration

### GPU Support

To use a GPU, install the correct JAX build for your CUDA version:

``` bash
pip install --upgrade "jax[cuda12]"
```

Refer to the official JAX installation guide for CUDA-specific wheels:
https://jax.readthedocs.io/en/latest/installation.html

If no GPU is available, Synema will run on CPU (training will be
slower).

------------------------------------------------------------------------

## What's in this repository

-   **`synema/`** --- Python package implementing models, data handling,
    and rendering utilities\
-   **`examples/`** --- Example scripts demonstrating training and
    inference on Cinema datasets\
-   **`data/`** --- Example assets and/or helper data\
-   **`pyproject.toml`** --- Modern Python packaging (PEP 621
    compliant)\
-   **`requirements-dev.txt`** --- Development tooling dependencies\ 
-   **`license.md`** --- Repository license

------------------------------------------------------------------------

## Requirements

Typical environment:

-   Python 3.9+
-   CUDA-capable GPU (recommended for training)
-   JAX ecosystem (jax, flax, optax)
-   Standard scientific Python libraries

------------------------------------------------------------------------

## Installation

### Core install

``` bash
pip install -e .
```

------------------------------------------------------------------------

## Quick Start

The repository includes two example Cinema databases:

-   **`dragon_elevation.cdb`** --- scalar image database\
-   **`tangle_rgb.cdb`** --- RGB image database

These are used by the example scripts in the `examples/` directory:

-   `cinema_scalar_image.py` → uses `dragon_elevation.cdb`
-   `cinema_rgb_image.py` → uses `tangle_rgb.cdb`

> The database paths are already hardcoded inside the example scripts.\
> You do **not** need to pass the database path via the command line.

### Run Scalar Image Example

``` bash
python examples/cinema_scalar_image.py
```

### Run RGB Image Example

``` bash
python examples/cinema_rgb_image.py
```

These scripts will:

1.  Load the corresponding Cinema database\
2.  Initialize the JAX/Flax NeRF-style model\
3.  Train or evaluate depending on script configuration\
4.  Produce rendered outputs / visualizations

Modify the script configuration directly if you want to change training
parameters, output paths, or rendering settings.

------------------------------------------------------------------------

## Cinema Data Expectations

Synema expects:

-   Images from a Cinema database
-   Camera pose and intrinsics metadata
-   Parameter metadata for consistent rendering

Adapters in `synema/` or `examples/` map Cinema metadata to NeRF
training inputs.

------------------------------------------------------------------------

## Project Structure

    synema/
      synema/        # Models, datasets, rendering, utilities
      examples/      # Training and rendering examples
      data/          # Example data
      pyproject.toml # Packaging configuration

------------------------------------------------------------------------

## Contributing

Contributions welcome via issues and pull requests:

-   New model variants
-   Dataset adapters
-   Performance improvements
-   Documentation updates

------------------------------------------------------------------------

## Citation

``` bibtex
@software{synema,
  title  = {Synema: Novel View Synthesis for Cinema in situ Visualization},
  author = {CinemaScience contributors},
  url    = {https://github.com/cinemascience/synema},
  year   = {2025}
}
```

------------------------------------------------------------------------

------------------------------------------------------------------------

## AI Assistance Disclosure

Portions of this repository's documentation, packaging configuration,
and test scaffolding were generated or refined with the assistance of AI
tools (including large language models).

All generated content has been reviewed and curated by the project
maintainers. Any errors, omissions, or inconsistencies remain the
responsibility of the human authors.

------------------------------------------------------------------------

## License

See `license.md`.
