Metadata-Version: 2.4
Name: neujoh-img
Version: 0.1.0
Summary: Structure-aware color ASCII art renderer with OKLab color and directional edges
Author: emjdp
License-Expression: MIT
Project-URL: Homepage, https://github.com/emjdp/NEUJOH.img
Project-URL: Repository, https://github.com/emjdp/NEUJOH.img.git
Project-URL: Issues, https://github.com/emjdp/NEUJOH.img/issues
Keywords: ascii-art,color-ascii-art,image-processing,oklab,terminal-art
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Artistic Software
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: src/neujoh/fonts/OFL.txt
Requires-Dist: numpy<3,>=2.0
Requires-Dist: opencv-python-headless<6,>=4.10
Requires-Dist: Pillow<13,>=10.4
Requires-Dist: scipy<2,>=1.14
Provides-Extra: matte
Requires-Dist: onnxruntime<2,>=1.20; extra == "matte"
Requires-Dist: rembg<3,>=2.0.60; extra == "matte"
Dynamic: license-file

# NEUJOH.img

NEUJOH.img는 이미지의 색과 구조를 보존하면서 문자로 다시 그리는 컬러 ASCII 아트 렌더러입니다.

> **N**eural **E**dge **U**nderstanding for **J**oint **O**ptical **H**alftoning, using **I**mage-**M**apped **G**lyphs

<p align="center">
  <img src="https://raw.githubusercontent.com/emjdp/NEUJOH.img/main/docs/full_wide.png" width="720" alt="NEUJOH.img로 변환한 컬러 ASCII 아트 예시">
</p>

## 무엇이 다른가요?

보통의 ASCII 아트가 밝기에 따라 문자를 고른다면, NEUJOH.img는 글리프의 실제 모양과 이미지의 국소 구조를 함께 비교합니다. 그래서 어두운 영역도 빈 공간이 되지 않고, 윤곽과 질감이 문자 안에 남습니다.

- 글리프를 4×8 잉크 커버리지 벡터로 바꾸고 형태가 가까운 문자를 선택합니다.
- DoG와 Sobel 방향을 이용해 강한 경계를 `-`, `/`, `|`, `\\`로 보강합니다.
- 선형 광과 OKLab에서 색을 처리해 컬러 ASCII 특유의 탁함을 줄입니다.
- 인물 매트를 선택적으로 사용해 피사체와 배경의 디테일을 따로 조절합니다.
- PNG, SVG, 일반 텍스트, 24비트 ANSI 출력을 지원합니다.

## 설치

Python 3.12 이상이 필요합니다. 기본 변환 기능은 PyPI에서 설치할 수 있습니다.

```bash
pip install neujoh-img
```

피사체 분리 기능까지 사용하려면 `matte` 추가 의존성을 함께 설치합니다.

```bash
pip install "neujoh-img[matte]"
```

저장소를 내려받아 개발하려면 다음을 사용합니다.

```bash
git clone https://github.com/emjdp/NEUJOH.img.git
cd NEUJOH.img

# 기본 설치
pip install -e .

# rembg와 ONNX Runtime을 포함한 전체 설치
pip install -e ".[matte]"
```

`rembg` 모델은 매트 기능의 첫 실행 때 내려받을 수 있으며, 기본 설치에서는 `--no-matte`를 사용하면 됩니다.

## 사용법

```bash
neujoh input.jpg \
  --cols 100 \
  --aspect 1:1 \
  --look film \
  --scale 2 \
  --svg \
  --ansi \
  -o result
```

이 명령은 `result.png`와 `result.txt`를 만들고, 옵션에 따라 `result.svg`와 `result.ans`도 만듭니다.

자주 쓰는 옵션:

| 옵션 | 설명 |
|---|---|
| `--cols` | 문자 격자의 가로 칸 수 |
| `--charset` | `ascii`, `code`, `blocks`, `mixed`, `minimal` |
| `--look` | `neutral`, `film`, `sunlit`, `neon`, `cold`, `mono` |
| `--aspect` | `1:1`, `16:9` 같은 출력 비율 |
| `--zoom`, `--focus-y` | 크롭 배율과 세로 초점 |
| `--detail`, `--structure` | 국소 디테일과 문자 구조 강도 |
| `--edges` | 방향성 경계 보강 강도 |
| `--bg-gain`, `--energy` | 셀 배경색과 광량 보존 정도 |
| `--invert` | 밝은 종이에 어두운 글자 스타일 |
| `--no-matte` | 피사체 분리 없이 변환 |

전체 옵션은 다음 명령으로 확인할 수 있습니다.

```bash
neujoh --help
```

`python -m neujoh`도 같은 명령을 실행합니다. 기존 저장소 사용자를 위해 `python ascii_art.py` 실행 방식도 유지됩니다.

Python 코드에서는 렌더러 API를 직접 사용할 수 있습니다.

```python
from PIL import Image
from neujoh import Config, composite, convert

source = Image.open("input.jpg")
config = Config(cols=100, matte=False)
result = convert(source, config)
composite(result, config).save("result.png")
```

## 파이프라인

1. 폰트의 각 글리프를 래스터라이즈하고 작은 커버리지 벡터로 압축합니다.
2. 선택적으로 피사체 매트를 계산해 전경과 배경을 분리합니다.
3. CLAHE, 언샤프, 국소 대비 정규화로 문자 선택용 디테일 채널을 만듭니다.
4. 방향성 경계를 검출해 실루엣과 주요 선을 보강합니다.
5. 선형 광에서 셀 색을 평균내고 OKLab에서 색감을 조정합니다.
6. 글리프 커버리지를 고려해 잉크와 배경의 광량을 보존하며 합성합니다.

핵심 합성식은 다음과 같습니다.

```text
coverage × ink + (1 − coverage) × wash = cell color
```

글자가 셀의 일부만 채우는 점을 보정하기 때문에 밝은 영역이 지나치게 어두워지지 않습니다.

## 구성

- `pyproject.toml`: 패키지 메타데이터, 의존성, `neujoh` 명령 정의
- `src/neujoh/renderer.py`: 변환 및 합성 파이프라인
- `src/neujoh/cli.py`: 명령줄 인터페이스
- `src/neujoh/fonts/`: 패키지에 포함되는 JetBrains Mono 폰트
- `ascii_art.py`: 기존 실행 방식과의 호환용 진입점
- `make_profile.py`: 여러 크롭과 해상도를 한 번에 만드는 배치 예제
- `sweep.py`: 주요 파라미터를 비교하는 콘택트 시트 생성기

## 라이선스

- 소스 코드와 문서는 [MIT License](LICENSE)로 공개합니다.
- 패키지에 포함된 JetBrains Mono 파일은 [SIL Open Font License 1.1](src/neujoh/fonts/OFL.txt)을 따릅니다.
- README 미리보기인 `docs/full_wide.png`는 MIT License 적용 대상이 아니며, 별도의 재사용 권한을 부여하지 않습니다.
