Metadata-Version: 2.4
Name: olimp
Version: 1.0.2
Summary: Framework for Image Precompensation
Author-email: Nafe Alkzir <nafe93@windowslive.com>, Arseniy Terekhin <senyai@gmail.com>, Sergey Gladilin <gladilin@gmail.com>, Dmitry Nikolaev <d.p.nikolaev@gmail.com>, Ivan Konovalenko <konovalenko@iitp.ru>
License: MIT
Project-URL: Homepage, https://github.com/pyolimp/pyolimp
Project-URL: Bug Reports, https://github.com/pyolimp/pyolimp/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: setuptools==69.0.3
Requires-Dist: requests==2.28.2
Requires-Dist: pillow>=11.2.1
Requires-Dist: numpy<2
Requires-Dist: torch<3,>=2.4.0
Requires-Dist: matplotlib==3.9.2
Requires-Dist: rich==13.8.0
Requires-Dist: torchvision>=0.19.0
Requires-Dist: piq==0.8.0
Requires-Dist: json5==0.9.24
Requires-Dist: pydantic>=2.6.4
Requires-Dist: segmentation_models_pytorch==0.3.4
Requires-Dist: ballfish==0.4.0
Requires-Dist: lpips==0.1.4
Dynamic: license-file

> 🌐 Эта страница также доступна на [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
```

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

### 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.

### Examples
#### Демонстрационный пример ДЦЗ
<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">
