Metadata-Version: 2.4
Name: embpred_deploy
Version: 0.1.3
Summary: Emb Deployment Package for Image Inference using Faster-RCNN and custom classification networks
Author-email: Berk Yalcinkaya <berkyalc@stanford.edu>
Project-URL: Homepage, https://github.com/berkyalcinkaya/embpred_deploy
Project-URL: Repository, https://github.com/berkyalcinkaya/embpred_deploy
Project-URL: Issues, https://github.com/berkyalcinkaya/embpred_deploy/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch>=1.9.0
Requires-Dist: torchvision>=0.10.0
Requires-Dist: opencv-python-headless>=4.5.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: tqdm>=4.60.0

# embpred_deploy Documentation

## Overview

`embpred_deploy` is a deployment package for running inference using **Faster-RCNN and custom classification networks**. It supports various input modes, including **timelapse inference**, **single-image inference**, and **multi-focal depth inference**.


## Installation

### 1. Create and activate a Conda environment with Python 3.12

To ensure compatibility, create a new Conda environment:

```bash
conda create -n embd python=3.12
conda activate embd
```

### 2. Install `embpred_deploy` via pip

Once the environment is set up, install the package:

```bash
pip install embpred_deploy
```

**Important**: The PyPI package does not include model weights due to size limitations. You must download the model weights separately (see Model Weights Installation below).

### 3. Install `embpred_deploy` via Git

Alternatively, if you prefer to pull the latest code directly from GitHub, run:

```bash
git clone https://github.com/berkyalcinkaya/embpred_deploy.git
cd embpred_deploy
pip install -e .
```


## Model Weights Installation

**⚠️ REQUIRED**: Pretrained model weights are NOT included in the PyPI package due to size limitations. You must download them separately to use the package.

Model weights are stored on Google Drive. To use the latest trained models, download the weight files from:

[Google Drive Weights](https://drive.google.com/file/d/1c-BJ0dvxzaZ4wMxMlhiRtwzURz7_ryaH/view?usp=sharing)

### Install Weights

After downloading the zip file, run the installation script to extract and move the weight files into the appropriate `models` folder:

```bash
python -m embpred_deploy.install_weights /path/to/your/downloaded_weights.zip
```

This script:
- Unzips the archive
- Moves any `.pth` or `.pt` files to the `embpred_deploy/models` directory

**Note**: The `embpred_deploy/models` directory will be created automatically if it doesn't exist.

## Usage Instructions

The inference script supports three modes:


### 1. **Timelapse Inference**

Use the `--timelapse-dir` argument to process a sequence of images. This mode supports two directory structures:

- **Single-image per timepoint**  
  - All images are stored in one directory.
  - Each image is loaded in grayscale and converted to RGB (duplicated channels).
  
- **Multiple focal depths per timepoint**  
  - The images must be organized into **three subdirectories**, each representing a different focal depth.
  - The script aligns images based on sorted filenames across subdirectories.

#### Example Command:

```bash
embpred_deploy --timelapse-dir /path/to/your/timelapse_data --model-name YOUR_MODEL_NAME
```

#### Output:
- Raw outputs: `raw_timelapse_outputs.npy`
- If `--postprocess` is enabled:
  - `max_prob_classes.csv`
  - `max_prob_classes.png`


### 2. **Single Image Inference**

Use the `--single-image` argument to run inference on a single image. The image is processed by duplicating its grayscale channel into RGB.

#### Example Command:

```bash
embpred_deploy --single-image /path/to/your/image.jpg --model-name YOUR_MODEL_NAME
```


### 3. **Three-Focal Depth Inference**

Provide three separate focal depth images using the `--F_neg15`, `--F0`, and `--F15` arguments.

#### Example Command:

```bash
embpred_deploy --F_neg15 /path/to/F_neg15.jpg --F0 /path/to/F0.jpg --F15 /path/to/F15.jpg --model-name YOUR_MODEL_NAME
```


## Assumptions & Notes

### **Input Image Format**
- **Single image inference**:  
  - Image is loaded in grayscale and converted to 3-channel RGB.
- **Timelapse mode**:  
  - Image filenames must be **sorted** to ensure correct timepoint alignment.

### **Model Output**
- **Regular inference**:  
  - The script maps raw model output to class labels.
- **Timelapse inference**:  
  - Raw probability vectors are returned unless `--postprocess` is enabled.

### **Dependencies**
The package requires the following libraries (installed via pip or Conda):
- `pytorch`
- `torchvision`
- `opencv-python`
- `numpy`
- `matplotlib`
- `tqdm`

Ensure these dependencies are installed in your environment before running inference.

## Development and Deployment

### Setting up for Development

To set up the development environment:

```bash
# Clone the repository
git clone https://github.com/berkyalcinkaya/embpred_deploy.git
cd embpred_deploy

# Install development dependencies
pip install -r requirements-dev.txt

# Install the package in editable mode
pip install -e .
```

### Deploying to PyPI

To deploy the package to PyPI:

1. **Install deployment tools:**
   ```bash
   pip install -r requirements-dev.txt
   ```

2. **Run the deployment script:**
   ```bash
   python build_and_deploy.py
   ```

3. **Or manually build and deploy:**
   ```bash
   # Clean previous builds
   rm -rf build/ dist/ *.egg-info/
   
   # Build the package
   python -m build
   
   # Check the package
   python -m twine check dist/*
   
   # Upload to TestPyPI (recommended first)
   python -m twine upload --repository testpypi dist/*
   
   # Upload to PyPI (production)
   python -m twine upload dist/*
   ```

### PyPI Credentials

You'll need to set up your PyPI credentials. Create a `~/.pypirc` file:

```ini
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
repository = https://upload.pypi.org/legacy/
username = your_username
password = your_password

[testpypi]
repository = https://test.pypi.org/legacy/
username = your_username
password = your_password
```

## Support

For further details or troubleshooting, please refer to the source code or contact the maintainers.
