olimp 1.0.6
Framework for Image Precompensation
License: MIT
Requires Python: >=3.10

> 🌐 Эта страница также доступна на [English 🇬🇧](./README.en.md)

# Pyolimp

Данный проект представляет собой фреймворк на основе методов машинного обучения для предкомпенсации изображений с целью коррекции нарушений зрения — в частности, дефектов цветового зрения (ДЦЗ) и рефракционных искажений (РИЗ).
Фреймворк включает в себя как нейросетевые, так и не нейросетевые модули, что позволяет эффективно решать задачу предкомпенсации различными методами.

## Обзор проекта

Данный проект направлен на предкомпенсацию визуальных нарушений с использованием методов машинного обучения.
Он представляет собой универсальный фреймворк, поддерживающий как нейросетевые (NN), так и не нейросетевые (non-NN) подходы для восстановления качества изображения у пользователей с различными нарушениями зрения. Направления прикладного использования следующие:

* Предкомпенсация дефектов цветового зрения (ДЦЗ):
Компенсация цветовой слепоты (например, протанопия, дейтеранопия).
* Предкомпенсация рефракционных искажений зрения (РИЗ):
Коррекция искажений, вызванных нарушениями рефракции, с улучшением чёткости и резкости изображения.
* Предкомпенсация других типов искажений:
Фреймворк может быть использован для обучения и применения обученных нейросетевых архитектур предкомпенсации искажений, отличных от ДЦЗ и РИЗ.

## Требования к проекту

* Python 3.10+
* Pytorch 2.4+
* Дополнительные зависимости, перечисленные в pyproject.toml

Технические характеристики ПК:
* аппаратная платформа, на которой может быть запущена 64-разрядная ОС Ubuntu версии 22.04 LTS или выше или Windows версии 10 и выше;
* не менее 16 ГБ оперативной памяти;
* восьмиядерный процессор x86 2.5 ГГц и выше или аналогичный ему;
* видеокарта с поддержкой cuda 12.+, и не менее 12 ГБ видеопамяти;
* не менее 100 ГБ свободного места на жёстком диске;
* клавиатура и мышь (или тачпад).


## Установка

```
pip install olimp
```
или
```
pip install git+https://github.com/pyolimp/pyolimp.git
```

## Обновление фреймворка до последней версии 

```
pip install -U olimp
```
или
```
pip install -U git+https://github.com/pyolimp/pyolimp.git
```

## Использование

### 1. Не нейросетевые модули для предкомпенсации ДЦЗ и РИЗ

Чтобы запустить алгоритм оптимизации для предкомпенсации РИЗ с использованием метода Брегмана-Джамбо, выполните:
```
python3 -m olimp.precompensation.optimization.bregman_jumbo
```

Чтобы запустить алгоритм оптимизации для предкомпенсации РИЗ с использованием метода Монталто, выполните:
```
python3 -m olimp.precompensation.optimization.montalto
```
Чтобы запустить алгоритм оптимизации для предкомпенсации ДЦЗ с использованием метода Тенненхольца-Зачевского, выполните:

```
python3 -m olimp.precompensation.optimization.tennenholtz_zachevsky
```

Вы также можете вызывать примеры из каталога `olimp.precompensation.basic` и `olimp.precompensation.analytics`, как в приведенных примерах.

В `docs/source/notebooks/precompensation.ipynb` представлены дополнительные примеры запуска различных не нейросетевых методов предкомпенсации РИЗ и ДЦЗ с краткими описаниями представленных методов и примерами результатов их работы. 
Для запуска необходимо последовательно запустить сначала первые ячейки с импортом общих библиотек, затем ячейку с интересующим методом.

### 2. Нейросетевые модули для предкомпенсации ДЦЗ и РИЗ

Чтобы запустить нейросетевую модель для предкомпенсации РИЗ с использованием метода USRNET, выполните:
```
python3 -m olimp.precompensation.nn.models.usrnet
```

Чтобы запустить нейросетевую модель для предкомпенсации ДЦЗ на основе архитектуры с использованием SWIN-трансформеров, выполните
```
python3 -m olimp.precompensation.nn.models.cvd_swin.Generator_transformer_pathch4_844_48_3_nouplayer_server5
```

В `docs/source/notebooks/precompensation_nn.ipynb` представлены дополнительные примеры запуска различных нейросетевых методов предкомпенсации РИЗ и ДЦЗ с краткими описаниями представленных методов и примерами результатов их работы. 
Для запуска необходимо последовательно запустить сначала первые ячейки с импортом общих библиотек, затем ячейку с интересующим методом.

### 3. Обучение моделей

Для обучения нейросетевых моделей предкомпенсации используйте следующую команду:

```
python3 -m olimp.precompensation.nn.train.train --config ./olimp/precompensation/nn/pipeline/usrnet.json
```
Вы также можете обучить другие модели, см. `olimp/precompensation/nn/pipeline`. Также у нас есть **json-схема**, которую можно сгенерировать, используя следующую команду:

```
python3 -m olimp.precompensation.nn.train.train --update-schema
```

В `docs/source/notebooks/pyolimp_train.ipynb` представлено пошаговое описание процесса обучения нейронной сети на примере нейросети USRNET.

### Примеры

> 📖 См. также [Примеры использования](./olimp/examples/README.md)

#### Демонстрационный пример ДЦЗ
<img src="https://github.com/user-attachments/assets/42f54054-dba1-4204-957e-29b1a44a690c">

#### Демонстрационный пример РИЗ
<img src="https://github.com/user-attachments/assets/7e35fe3b-7667-4530-8c79-a1263749eeff">