# Assignment 1: Rendering Basics

Open `index.html` for the report, `assets/` for the renders, and `ASSIGNMENT.md` for the original instructions.

## Setup on an Apple Silicon Mac

Install Xcode Command Line Tools (`xcode-select --install`) and [uv](https://docs.astral.sh/uv/).
These PyTorch wheels need ARM Python; an older Intel Homebrew Python will not work.

```sh
uv python install cpython-3.11-macos-aarch64-none
uv venv --python cpython-3.11-macos-aarch64-none .venv
source .venv/bin/activate
uv pip install torch==2.4.1 torchvision==0.19.1 'numpy<2' setuptools wheel ninja fvcore iopath
MAX_JOBS=4 MACOSX_DEPLOYMENT_TARGET=11.0 uv pip install --no-build-isolation -r requirements-lock.txt
```

Tested with Python 3.11.15, PyTorch 2.4.1, and PyTorch3D 0.7.8 on macOS ARM64.
Package versions are in `requirements-lock.txt` and machine details in `environment.json`.
Renders run on the CPU with four PyTorch threads. There is no training step.

Recorded animation times total about 20 minutes, including 13 minutes for the RGB-D comparison.
This excludes setup, geometry construction, and most GIF encoding time.

## Run

From this folder, with the environment activated:

```sh
python main.py
python test_geometry.py
```

Defaults: 256 × 256 pixels per view, 60 frames, 15 fps, seed 7. GIFs loop continuously.
RGB-D images are unprojected at full resolution, then every eighth point is rendered.
Use `--point_stride 1` for all points; this takes substantially longer on the CPU.
Sections can be run separately: `1`, `2`, `3`, `4`, `5`, `5.1`, `5.2`, `5.3`, `6`, or `7`.

```sh
python main.py --section 5.2
python main.py --section all --image_size 128 --num_frames 8 --output_dir preview
```

`python main.py` runs all sections. The original `python -m starter.assignment` command also works.

Save previews to a separate directory to avoid overwriting the final renders.
`assets/timings.json` records each animation's rendering time. Only the dolly entry
includes GIF encoding. Rerunning a section updates its timings.

## Code

- `main.py`: entry point for running the assignment.
- `starter/assignment.py`: section runner, camera orbits, GIFs, and comparison panels.
- `starter/geometry.py`: meshes, parametric/implicit surfaces, snowman, and surface sampling.
- `starter/dolly_zoom.py` and `starter/camera_transforms.py`: completed camera exercises.
- `starter/utils.py`, `starter/render_mesh.py`, and `starter/render_generic.py`: supplied helpers and examples, with small corrections.
- `test_geometry.py`: checks topology, surface equations, color interpolation, camera matrices, dolly-zoom height, and sampling.

The report opens offline. For a local server, run `python -m http.server 8000`
and visit `http://localhost:8000`.

## Canvas submission

Upload `jjacob2_code_proj1.zip`. It contains the `jjacob2_code_proj1/` folder with
the entry point, source code, input data, setup instructions, tests, and report.
The Python environment and caches are excluded. Publishing the webpage to the
course website is a separate submission step.

## Verification

All six geometry tests pass, all 24 local file links resolve, and the 15 GIFs each
have 60 frames, a four-second duration, and continuous looping. Camera results were
checked against the reference views, along with representative frames from every section.

## Sources

Starter code, data, and reference images: [learning3d/assignment1](https://github.com/learning3d/assignment1),
commit `168cb6a69a96cc26024b528eb719923c0f10b65a`.
PyTorch3D is pinned to commit `75ebeeaea0908c5527e7b1e305fbc7681382db47`.
The reference images remain in `images/`; all report renders are generated into `assets/`.
