Metadata-Version: 2.5
Name: modulaic
Version: 0.1.0
Summary: A configurable, condition-aware image-to-image translation toolkit for PyTorch: U-Net generators, PatchGAN discriminators, and pluggable auxiliary-vector conditioning (bottleneck injection and FiLM) for GAN-based CV/DL tasks.
Project-URL: Homepage, https://github.com/rahulvijay007/modulaic
Project-URL: Documentation, https://github.com/rahulvijay007/modulaic/tree/main/docs
Project-URL: Issues, https://github.com/rahulvijay007/modulaic/issues
Author-email: Rahul V <rahul160503@gmail.com>
License: MIT
License-File: LICENSE
Keywords: computer-vision,conditional-generation,deep-learning,feature-wise-linear-modulation,gan,image-to-image-translation,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21
Requires-Dist: pyyaml>=6.0
Requires-Dist: torch>=1.13
Provides-Extra: all
Requires-Dist: albumentations>=1.3; extra == 'all'
Requires-Dist: pillow>=9.0; extra == 'all'
Requires-Dist: scikit-image>=0.19; extra == 'all'
Provides-Extra: augment
Requires-Dist: albumentations>=1.3; extra == 'augment'
Provides-Extra: data
Requires-Dist: pillow>=9.0; extra == 'data'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Provides-Extra: metrics
Requires-Dist: scikit-image>=0.19; extra == 'metrics'
Description-Content-Type: text/markdown

# modulaic

**Configurable, condition-aware image-to-image translation for PyTorch.**

`modulaic` provides a generator/discriminator pair for image-to-image translation tasks where
the desired output depends not only on the input image, but also on an auxiliary vector of
side-channel information — a class label, a set of continuous measurements, a style code, a
sensor or acquisition parameter, or any other numeric context that should influence the
translation. It packages this as reusable, configurable `torch.nn.Module` building blocks rather
than a fixed architecture, so it can be dropped into a wide range of computer vision and deep
learning tasks: conditional style transfer, cross-domain translation, restoration or enhancement
conditioned on capture metadata, sensor calibration, and similar problems.

## Why

Most publicly available image-to-image GAN implementations either ignore auxiliary conditioning
entirely, or bake a single, fixed conditioning mechanism into the architecture. `modulaic` treats
*how* a condition vector reaches the network as a first-class, swappable choice:

- **`BOTTLENECK`** — the condition vector is projected and concatenated into the encoder's
  bottleneck feature map, spatially broadcast to match its resolution.
- **`FILM`** — the condition vector is projected into a shared embedding that feature-wise
  linearly modulates (scale and shift) the output of every decoder stage.
- **`BOTH`** — both pathways are active simultaneously (the default; empirically the most
  effective when the amount of conditioning signal is small relative to the network's depth).
- **`NONE`** — conditioning is disabled entirely, useful as an unconditional baseline.

The strategy is a single constructor argument, so the same model definition can be used to run a
conditioned/unconditioned ablation without touching the rest of the training code.

## Installation

```bash
pip install modulaic
```

Optional extras:

```bash
pip install modulaic[data]      # image I/O for the built-in dataset (Pillow)
pip install modulaic[metrics]   # SSIM support (scikit-image)
pip install modulaic[augment]   # synchronized paired-image augmentation (albumentations)
pip install modulaic[all]       # everything above
```

## Quickstart

```python
import torch
from modulaic.models import ConditionalUNetGenerator, PatchDiscriminator, ConditioningStrategy

generator = ConditionalUNetGenerator(
    in_channels=3,
    out_channels=3,
    condition_dim=4,
    depth=5,
    base_channels=64,
    conditioning_strategy=ConditioningStrategy.BOTH,
)
discriminator = PatchDiscriminator(in_channels=3)

image = torch.randn(2, 3, 256, 256)
condition = torch.randn(2, 4)

translated = generator(image, condition)      # (2, 3, 256, 256)
patch_scores = discriminator(translated)      # (2, 1, 30, 30)
```

Training end-to-end with the built-in trainer:

```python
from modulaic.training import GANTrainer, GANLossConfig
from modulaic.data import PairedConditionalDataset

dataset = PairedConditionalDataset("manifest.json")
trainer = GANTrainer(
    generator=generator,
    discriminator=discriminator,
    loss_config=GANLossConfig(adversarial="lsgan", reconstruction="l1", reconstruction_weight=100.0),
    use_amp=True,
    grad_accumulation_steps=4,
)
trainer.fit(dataset, epochs=100, batch_size=4, checkpoint_dir="checkpoints/")
```

See `examples/quickstart.py` for a fully self-contained, synthetic-data run, and `docs/` for the
architecture reference, usage guide, and full API documentation.

## Command line interface

```bash
modulaic train --config config.yaml
modulaic evaluate --config config.yaml --checkpoint checkpoints/best.pt
modulaic infer --checkpoint checkpoints/best.pt --input image.png --condition 0.1,0.2,0.3,0.4 --output result.png
```

## Features

- Configurable-depth U-Net generator (2-6 levels) with selectable normalization
  (`batch` / `instance` / `group`).
- PatchGAN-style discriminator with configurable depth and width.
- Four conditioning strategies (`none`, `bottleneck`, `film`, `both`), selectable per-model.
- Loss registry: `vanilla`, `lsgan`, and `hinge` adversarial losses; `l1` and `l2` reconstruction
  losses, freely combinable with configurable weighting.
- Mixed-precision training, gradient accumulation, alternating discriminator/generator updates,
  checkpoint/resume, and optional generator EMA (exponential moving average) in `GANTrainer`.
- PSNR, SSIM, MAE, and R-squared evaluation metrics.
- A simple, dataset-agnostic paired-image manifest format for supervised image-to-image training.
- Dataclass-based configuration with YAML load/save, and a `modulaic` CLI.

## License

MIT — see [LICENSE](LICENSE).
