Metadata-Version: 2.4
Name: decimer_segmentation
Version: 1.6.0
Summary: DECIMER Segmentation - Extraction of chemical structure depictions from scientific literature
Home-page: https://github.com/Kohulan/DECIMER-Image-Segmentation
Author: Kohulan Rajan
Author-email: kohulan.rajan@uni-jena.de
Maintainer: Kohulan Rajan
Maintainer-email: kohulan.rajan@uni-jena.de
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tensorflow<=2.15.1,>=2.12.0
Requires-Dist: numpy>=1.2.0
Requires-Dist: scikit-image>=0.2.0
Requires-Dist: pillow
Requires-Dist: opencv-python
Requires-Dist: matplotlib
Requires-Dist: IPython
Requires-Dist: numba
Requires-Dist: scipy
Requires-Dist: requests
Requires-Dist: pystow
Requires-Dist: pypdfium2<6,>=4.30.0
Provides-Extra: pdf
Requires-Dist: PyMuPDF; extra == "pdf"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">

# 🔬 DECIMER Image Segmentation 📄

### Deep Learning for Chemical Image Recognition - Automated Structure Detection & Extraction

<p align="center">
  <img src="https://github.com/Kohulan/DECIMER-Image-Segmentation/blob/master/Validation/Abstract1.png?raw=true" alt="DECIMER Segmentation" width="700">
</p>

[![License](https://img.shields.io/badge/License-MIT%202.0-blue.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg?style=for-the-badge)](https://GitHub.com/Kohulan/DECIMER-Image-Segmentation/graphs/commit-activity)
[![GitHub issues](https://img.shields.io/github/issues/Kohulan/DECIMER-Image-Segmentation.svg?style=for-the-badge)](https://GitHub.com/Kohulan/DECIMER-Image-Segmentation/issues/)
[![GitHub contributors](https://img.shields.io/github/contributors/Kohulan/DECIMER-Image-Segmentation.svg?style=for-the-badge)](https://GitHub.com/Kohulan/DECIMER-Image-Segmentation/graphs/contributors/)
[![tensorflow](https://img.shields.io/badge/TensorFlow-2.10.1-FF6F00.svg?style=for-the-badge&logo=tensorflow)](https://www.tensorflow.org)
[![Model Card](https://img.shields.io/badge/Model_Card-Mask_RCNN-9cf.svg?style=for-the-badge)](https://zenodo.org/badge/latestdoi/268631290)
[![DOI](https://zenodo.org/badge/268631290.svg)](https://zenodo.org/badge/latestdoi/268631290)
[![GitHub release](https://img.shields.io/github/release/Kohulan/DECIMER-Image-Segmentation.svg?style=for-the-badge)](https://GitHub.com/Kohulan/DECIMER-Image-Segmentation/releases/)
[![PyPI version fury.io](https://badge.fury.io/py/decimer-segmentation.svg?style=for-the-badge)](https://pypi.python.org/pypi/decimer-segmentation/)

**🌐 Try it live at [decimer.ai](https://decimer.ai)**

</div>

---

## 📚 Table of Contents

- [📝 Overview](#-overview)
- [✨ Key Features](#-key-features)
- [🎯 How It Works](#-how-it-works)
- [⚙️ Installation](#️-installation)
- [🚀 Usage](#-usage)
  - [Command Line](#command-line-interface)
  - [Python API](#python-api)
  - [Windows Users](#-notes-for-windows-users)
- [📊 Model Information](#-model-information)
- [📄 Citation](#-citation)
- [🙏 Acknowledgements](#-acknowledgements)
- [👥 Authors](#-authors)
- [🌐 Project Website](#-project-website)
- [🏛️ Research Group](#️-research-group)

---

## 📝 Overview

<div align="center">
  <img src="https://github.com/Kohulan/DECIMER-Image-to-SMILES/raw/master/assets/DECIMER.gif" width="350" align="right">
</div>

> **Unlocking decades of chemical knowledge from scientific literature!**
>
> Chemistry has accumulated vast amounts of knowledge about chemical compounds, structures, and properties across countless scientific publications. DECIMER Segmentation is the first open-source, deep learning-based tool designed to automatically recognize and extract chemical structure depictions from scientific documents.

### 🎯 The Challenge

Converting images of chemical structures into machine-readable formats (OCSR - Optical Chemical Structure Recognition) is a crucial step in digitizing chemical knowledge. But before we can recognize structures, we need to find and extract them from complex document pages!

### 💡 The Solution

DECIMER Segmentation uses advanced deep learning to:
- 🔍 **Detect** chemical structure depictions in scientific publications
- ✂️ **Extract** individual structure images with precision
- 📚 **Process** both modern PDFs and scanned historical documents
- ⚡ **Automate** the entire workflow from document to segmented structures

---

## ✨ Key Features

<table>
  <tr>
    <td width="33%" align="center">
      <h3>🤖 Deep Learning Powered</h3>
      <p>Built on Mask R-CNN architecture for state-of-the-art detection accuracy</p>
    </td>
    <td width="33%" align="center">
      <h3>📖 Universal Compatibility</h3>
      <p>Works with PDFs, scanned pages, and bitmap images from any publisher</p>
    </td>
    <td width="33%" align="center">
      <h3>🆓 Open Source</h3>
      <p>Freely available code and pre-trained models for the community</p>
    </td>
  </tr>
  <tr>
    <td width="33%" align="center">
      <h3>⚡ High Performance</h3>
      <p>GPU acceleration support for rapid batch processing</p>
    </td>
    <td width="33%" align="center">
      <h3>🎨 Smart Post-Processing</h3>
      <p>Automatic mask expansion to capture complete structures</p>
    </td>
    <td width="33%" align="center">
      <h3>🌐 Web Application</h3>
      <p>User-friendly interface available at decimer.ai</p>
    </td>
  </tr>
</table>

---

## 🎯 How It Works

DECIMER Segmentation employs a sophisticated two-stage workflow:

### 1️⃣ **Detection Stage**
```
📄 Input Document → 🤖 Mask R-CNN Model → 🎭 Structure Masks
```
The deep learning model analyzes the page and creates precise masks indicating the location of each chemical structure.

### 2️⃣ **Post-Processing Stage**
```
🎭 Initial Masks → 🔧 Expansion Algorithm → ✅ Complete Structures
```
An intelligent post-processing workflow ensures that potentially incomplete masks are expanded to capture the full structure.

### 🎨 Visual Workflow

```
┌─────────────────┐
│  PDF/Image File │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Page Extraction│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Mask R-CNN      │
│ Detection       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Mask Expansion  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Segmented       │
│ Structures      │
└─────────────────┘
```

---

## ⚙️ Installation

### 🐍 Prerequisites

We strongly recommend using a Conda environment for seamless dependency management.

#### Install Miniconda (if not already installed)

```bash
# Linux
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

# macOS
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
bash Miniconda3-latest-MacOSX-x86_64.sh
```

### 📦 Installation Options

<details>
<summary><b>Option 1: Install from GitHub (Development Version)</b></summary>

```bash
# Clone the repository
git clone https://github.com/Kohulan/DECIMER-Image-Segmentation.git
cd DECIMER-Image-Segmentation

# Create and activate conda environment
conda create --name DECIMER_IMGSEG python=3.10
conda activate DECIMER_IMGSEG

# Install dependencies
conda install pip
python -m pip install -U pip

# Install DECIMER-Segmentation
pip install .

# Optional: PyMuPDF as an alternative PDF reader (licensed under the AGPL-3.0)
pip install ".[pdf]"
```

</details>

<details>
<summary><b>Option 2: Install from PyPI (Stable Release)</b></summary>

```bash
# Create and activate conda environment
conda create --name DECIMER_IMGSEG python=3.10
conda activate DECIMER_IMGSEG

# Install from PyPI
pip install decimer-segmentation

# Optional: PyMuPDF as an alternative PDF reader (licensed under the AGPL-3.0)
pip install "decimer-segmentation[pdf]"
```

</details>

#### 📄 Reading PDFs

PDF pages are rendered at 300 DPI with [pypdfium2](https://github.com/pypdfium2-team/pypdfium2) (Apache-2.0 /
BSD-3-Clause), which is installed with `decimer-segmentation`, so a plain `pip install decimer-segmentation` reads PDFs.
No extra program is needed (Poppler is no longer used, and the `poppler_path` argument is ignored).

[PyMuPDF](https://pymupdf.readthedocs.io/) can be used instead. It is licensed under the AGPL-3.0 while this package is
MIT-licensed, so it is an optional extra that is never imported unless you ask for it:

```bash
pip install "decimer-segmentation[pdf]"
```

```python
segments = segment_chemical_structures_from_file("document.pdf", pdf_backend="pymupdf")  # default: "pdfium"
```

On the command line: `python3 segment_structures_in_document.py document.pdf --pdf-backend pymupdf` (`--pdf_backend` works too). Without PyMuPDF
installed, `pdf_backend="pymupdf"` raises an `ImportError` that tells you how to install it. Images (PNG, JPEG, ...) and
numpy arrays need neither reader.

**Changed in 1.6.0:**

- PDFs are read with pypdfium2 instead of PyMuPDF, which is no longer installed with the package. The two readers draw the
  same pages with slightly different anti-aliasing, so a few bounding boxes can differ by some pixels, or include a dashed
  frame that the other reader leaves out; `pdf_backend="pymupdf"` renders the pages as 1.5.x did. Pages are rendered one
  after the other, because neither reader is thread-safe.
- The model is downloaded and loaded on first use instead of at import, so `set_inference_config()` and the command-line
  `--fast` flag now take effect (before, the model was already loaded when they ran). With `--fast`,
  `DETECTION_MIN_CONFIDENCE` is 0.7 instead of 0.75; the default mode is unchanged.

#### 📥 The model is downloaded on first use

Importing `decimer_segmentation` does not download or load anything. The first segmentation (or an explicit call to
`decimer_segmentation.get_model()`) downloads the Mask R-CNN weights (about 270 MB) if they are missing, loads the
model and keeps it for later calls. The weights live in `$PYSTOW_HOME/DECIMER-Segmentation_model/`
(`~/.data/DECIMER-Segmentation_model/` by default); weights that are already there are used without network access.

### 🖥️ Hardware Requirements

- **CPU Mode**: Works on any modern CPU
- **GPU Mode** *(Recommended)*: CUDA-compatible GPU with appropriate drivers
  - Significantly faster processing
  - Essential for batch processing

---

## 🚀 Usage

### Command Line Interface

Process entire documents with a single command:

```bash
# Segment structures from a PDF or image file
python3 segment_structures_in_document.py your_document.pdf

# Output will be saved in a folder named after your input file
# e.g., your_document/ containing all segmented structures
```

### Python API

#### 🎨 **Example 1: Segment from Image Array**

```python
from decimer_segmentation import segment_chemical_structures
import cv2

# Load your scanned page
page_image = cv2.imread("path/to/scanned_page.png")

# Extract all chemical structures
segments = segment_chemical_structures(page_image, expand=True)

# segments is a list of numpy arrays, each containing a structure
for idx, structure in enumerate(segments):
    cv2.imwrite(f"structure_{idx}.png", structure)
    print(f"✅ Saved structure {idx}")
```

#### 📄 **Example 2: Segment from File (PDF or Image)**

```python
from decimer_segmentation import segment_chemical_structures_from_file

# Process a PDF file
segments = segment_chemical_structures_from_file(
    "path/to/document.pdf",
    expand=True
)

# Process an image file
segments = segment_chemical_structures_from_file(
    "path/to/page_image.jpg",
    expand=True
)

print(f"🎉 Extracted {len(segments)} chemical structures!")
```

To find out where each structure was found, ask for the bounding boxes and the page numbers:

```python
segments, bboxes, page_numbers = segment_chemical_structures_from_file(
    "path/to/document.pdf",
    expand=True,
    return_bboxes=True,         # (y0, x0, y1, x1) in pixels of the page image
    return_page_numbers=True,   # the page of the PDF, counted from 1
)

for segment, bbox, page_number in zip(segments, bboxes, page_numbers):
    print(f"Page {page_number}: structure at {bbox}")
```

There is one bounding box and one page number per segment, in the order of the segments. The pages of a PDF are
rendered at 300 DPI, and the bounding boxes are in pixels of these page images. Every segment of an image file is on
page 1. Which values are returned depends on the two options:

| `return_bboxes` | `return_page_numbers` | Returns |
|---|---|---|
| `False` (default) | `False` (default) | `segments` |
| `True` | `False` | `(segments, bboxes)` |
| `False` | `True` | `(segments, page_numbers)` |
| `True` | `True` | `(segments, bboxes, page_numbers)` |

#### 🔧 **Example 3: Batch Processing**

```python
from decimer_segmentation import segment_chemical_structures_from_file
import os
from pathlib import Path

def batch_segment(input_dir, output_dir):
    """Process multiple PDF files"""
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    
    for pdf_file in Path(input_dir).glob("*.pdf"):
        print(f"📄 Processing {pdf_file.name}...")
        
        segments = segment_chemical_structures_from_file(
            str(pdf_file),
            expand=True
        )
        
        # Save each segment
        file_output_dir = Path(output_dir) / pdf_file.stem
        file_output_dir.mkdir(exist_ok=True)
        
        for idx, segment in enumerate(segments):
            output_path = file_output_dir / f"structure_{idx:03d}.png"
            cv2.imwrite(str(output_path), segment)
        
        print(f"✅ Extracted {len(segments)} structures from {pdf_file.name}")

# Use it
batch_segment("input_pdfs/", "output_structures/")
```

#### 🎯 **Example 4: Advanced Usage with Custom Parameters**

```python
from decimer_segmentation import segment_chemical_structures
import cv2

# Load image
image = cv2.imread("complex_page.png")

# Segment with custom settings
segments = segment_chemical_structures(
    image,
    expand=True,          # Enable mask expansion
    visualization=True    # Generate visualization (if available)
)

# Process results
for idx, segment in enumerate(segments):
    # You can now pass this to DECIMER Image Transformer
    # for structure recognition
    print(f"Structure {idx}: {segment.shape}")
```

### 📓 Interactive Tutorial

For more comprehensive examples and interactive demonstrations, check out our **[Jupyter Notebook](https://github.com/Kohulan/DECIMER-Image-Segmentation/blob/master/DECIMER_Segmentation_notebook.ipynb)**!

---

### 🪟 Notes for Windows Users

<details>
<summary><b>Windows-Specific Instructions</b></summary>

#### 1️⃣ Use Anaconda PowerShell Prompt
Run all commands in the **Anaconda PowerShell Prompt** (not regular Command Prompt or PowerShell).

#### 2️⃣ PDF Support

PDF files are read with pypdfium2, which is installed with the package and needs no extra program on Windows
(Poppler is no longer used, and the `poppler_path` argument is ignored).

#### 3️⃣ GPU Support on Windows
Ensure you have:
- CUDA Toolkit installed
- cuDNN libraries configured
- Compatible GPU drivers

</details>

---

## 📊 Model Information

### 🤖 Pre-trained Model

The Mask R-CNN model is publicly available and ready to use:

**[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10142866.svg)](https://doi.org/10.5281/zenodo.10142866)**

### 🎓 Model Architecture

- **Base Network**: Mask R-CNN
- **Training Data**: Diverse chemical literature from multiple publishers
- **Task**: Instance segmentation of chemical structure depictions
- **Performance**: Manually validated on publications from various sources

### 🔍 Model Performance

The model has been rigorously evaluated on:
- ✅ Publications from multiple scientific publishers
- ✅ Documents spanning different time periods
- ✅ Both modern PDFs and scanned historical pages
- ✅ Various image qualities and layouts

---

## 📄 Citation

If DECIMER Segmentation contributes to your research, please cite:

```bibtex
@article{Rajan2021,
  author = {Rajan, Kohulan and Brinkhaus, Henning Otto and Sorokina, Maria and Zielesny, Achim and Steinbeck, Christoph},
  title = {DECIMER-Segmentation: Automated extraction of chemical structure depictions from scientific literature},
  journal = {Journal of Cheminformatics},
  year = {2021},
  volume = {13},
  number = {20},
  doi = {10.1186/s13321-021-00496-1}
}
```

**Full Citation:**  
Rajan, K., Brinkhaus, H.O., Sorokina, M. et al. *DECIMER-Segmentation: Automated extraction of chemical structure depictions from scientific literature.* J Cheminform **13**, 20 (2021). https://doi.org/10.1186/s13321-021-00496-1

---

## 🙏 Acknowledgements

<div align="center">

### 🌟 Special Thanks

This project wouldn't be possible without the support and contributions from the community and funding organizations.

<table>
  <tr>
    <td align="center">
      <strong>Contributors</strong><br>
      All our amazing contributors who helped improve the codebase
    </td>
    <td align="center">
      <strong>Community</strong><br>
      Users providing feedback and reporting issues
    </td>
    <td align="center">
      <strong>Open Source</strong><br>
      Projects we build upon: TensorFlow, Mask R-CNN
    </td>
  </tr>
</table>

</div>

## 🌐 Project Website

<div align="center">

### Experience DECIMER Live!

<a href="https://decimer.ai">
  <img src="https://github.com/Kohulan/DECIMER-Image_Transformer/blob/master/DECIMER_V2.png?raw=true" width="600" alt="DECIMER.ai">
</a>

**[🚀 Try DECIMER.ai](https://decimer.ai)** - Web application.

### 📦 Complete DECIMER Suite

DECIMER Segmentation is part of a comprehensive chemical structure recognition pipeline:

1. **🔍 [DECIMER Segmentation](https://github.com/Kohulan/DECIMER-Image-Segmentation)** *(You are here)*  
   Extract chemical structures from documents

2. **🧠 [DECIMER Image Transformer](https://github.com/Kohulan/DECIMER-Image_Transformer)**  
   Convert structure images to SMILES strings

3. **🗄️ [MARCUS](https://marcus.decimer.ai/)**  
   Molecular Annotation and Recognition for Curating Unravelled Structures

</div>

---

## 🏛️ Research Group

<div align="center">

### 🎓 Maintained by the [Kohulan](https://www.kohulanr.com/#) @ Steinbeck Group

<a href="https://cheminf.uni-jena.de">
<img src="https://github.com/Kohulan/DECIMER-Image-to-SMILES/blob/master/assets/CheminfGit.png" width="400" alt="Cheminformatics Group"/>
</a>

**[Natural Products Cheminformatics Research Group](https://cheminf.uni-jena.de)**  
Institute for Inorganic and Analytical Chemistry  
Friedrich Schiller University Jena, Germany

---

## ⭐ Star History

<div align="center">

[![Star History Chart](https://api.star-history.com/svg?repos=Kohulan/DECIMER-Image-Segmentation&type=Date)](https://star-history.com/#Kohulan/DECIMER-Image-Segmentation&Date)

</div>

---

## 📊 Project Analytics

<div align="center">

![Repobeats](https://repobeats.axiom.co/api/embed/5a62f88de9624eca3a4bbfbdde6126fb8fb4c65d.svg "Repobeats analytics image")

</div>

---

<div align="center">

### 🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request.

**[📝 Report Bug](https://github.com/Kohulan/DECIMER-Image-Segmentation/issues)** · **[💡 Request Feature](https://github.com/Kohulan/DECIMER-Image-Segmentation/issues)** · **[⭐ Star this repo](https://github.com/Kohulan/DECIMER-Image-Segmentation)**

---

**Made with ❤️ and ☕ for the global chemistry community**

**© 2025 Kohulan @ Steinbeck Lab, Friedrich Schiller University Jena**

---

<sub>🔬 Advancing Open Science in Chemistry | 🌍 Digitizing Chemical Knowledge | 🤖 Powered by Deep Learning</sub>

</div>
