NEW LINE ART

NEW LINE ART converts a prepared color-region image into patch-based line art, supports guide-stroke and concentric flow generation, and can export still images or animated frame sequences including Wave, Steam, and Adjacent Flow.

NEW LINE ART 會將預先製作的色塊標記圖轉換成以 patch 為單位的流線藝術，支援導向筆畫、同心圓流線、靜態輸出，以及 Wave、Steam、Adjacent Flow 動畫影格輸出。

Quick Links / 快速連結

• English Tutorial
• 中文教學

English Tutorial

Current status and workflow

The repository currently provides two supported entry points:

• main_app.py: local Gradio web UI.
• pyqt_app.py: local PyQt6 desktop UI; it does not start a web server.

The two interfaces share the same processing backend, but their available controls are not identical:

Step	Gradio (main_app.py)	PyQt (pyqt_app.py)
1. Region segmentation	Active. Rule-based color-patch segmentation.	Active. Uses the same color-patch segmentation backend.
2. Flow guidance	Brush, eraser, and a frontend curve tool.	Brush, eraser, and a concentric-center marker action.
3. Line-art generation	Marker/Hypnotic styles, selectable concentric patches, tensor preview, cache controls, PNG/SVG downloads.	Marker/Hypnotic styles, selectable concentric patches, PNG/SVG save actions.
4. Animation	Wave Flow, directional Steam Flow, and forward/backward Adjacent Flow; PNG frames plus GIF preview, or SVG frames. Wave Flow can optionally lock one endpoint.	The same Wave, Steam, and Adjacent Flow effects, including Steam curl strength.
5. Contour compositing	The tab is present but currently disabled.	Active: overlays an uploaded contour image on the generated line art.

Step 1 is not SAM/SAM2 semantic segmentation. It is a deterministic color-segmentation pipeline designed for prepared images with a black background, white region boundaries, and colored or mid-gray interiors. No model checkpoint or GPU is required by the active segmentation flow.

System requirements

• Operating system: Windows, Linux, or macOS.
• Python: use Python 3.11 for the current pinned dependency set. In particular, scipy==1.16.3 and scikit-image==0.26.0 require Python 3.11 or later.
• Memory: 8 GB or more is recommended. Larger images and denser streamline settings require more memory and processing time.
• CPU execution is supported; the active workflow does not require a GPU.
• Disk space: allow room for Python packages and generated PNG, SVG, and GIF files.

Required and optional tools

• Python and pip: required to run and install the project.
• Git: required to clone the repository and to install the Git-based CLIP dependency in requirements.txt.
• Conda or Mamba: optional alternatives for managing the environment.
• Gradio: provides the local web UI.
• PyQt6: provides the desktop UI.
• NumPy, OpenCV, SciPy, and Pillow: provide the main app's image processing and numerical runtime.
• The dependency files also retain packages used by archived prototypes and related project components.

Clone the repository

For a complete checkout, including the wave_flow_simulation Git submodule:

git clone --recurse-submodules https://github.com/BobLynn/new-lineart.git
cd new-lineart

If the repository was cloned without submodules:

git submodule update --init --recursive

The current Gradio and PyQt entry points do not import the submodule directly, but initializing it keeps the repository checkout complete.

Install the environment

Choose one installation method.

Method 1: create a Python 3.11 Conda or Mamba environment

conda create -n new-lineart python=3.11 pip git
conda activate new-lineart
python install_requirements.py

Or:

mamba create -n new-lineart python=3.11 pip git
mamba activate new-lineart
python install_requirements.py

The checked-in environment.yml still declares Python 3.10, and install_requirements.py currently only rejects Python versions below 3.9. Those two declarations are older than the pinned dependency set and should not be used as proof of compatibility; until they are aligned, create a Python 3.11 environment explicitly as shown above.

Method 2: existing Python 3.11+ environment

The provided installer validates the Python version and then installs requirements.txt:

python install_requirements.py

Alternatively, install the file directly:

python -m pip install -r requirements.txt

You may use venv, Conda, Mamba, or another environment manager. If conda activate or mamba activate is unavailable, initialize the shell and reopen it; for example, use conda init powershell on Windows PowerShell or conda init bash on Linux/macOS Bash.

Run the Gradio app

python main_app.py

By default, the app listens on:

http://127.0.0.1:7860

The launch address can be changed with:

• GRADIO_SERVER_NAME (default 127.0.0.1)
• GRADIO_SERVER_PORT (default 7860)

Run the PyQt desktop app

python pyqt_app.py

The PyQt interface runs locally without a browser or web server. After the dependencies are installed, the current processing workflow does not require an internet connection.

Processing defaults and outputs

• NEW_LINEART_MAX_SIDE limits the longest side of the working image. The current code default is 800 pixels.
• Images larger than this limit are resized proportionally before segmentation, so generated results use the working resolution rather than the original large resolution.
• Step 3 line spacing is adjustable from 6 to 24 pixels and defaults to 12 pixels.
• Step 4 accepts 10 to 120 frames and defaults to 30 frames in both UIs.
• Steam Flow reuses the selected wind direction and strength, with a separate curl-strength control. It starts from every original streamline, groups adjacent lines, and periodically merges them into a narrow set of patch-derived average filaments before releasing them back to the source geometry.
• Generated still images are written under outputs/ as PNG and SVG files.
• Animation frames are written to timestamped outputs/flow_animation_* directories. PNG animation generation also creates lineart_flow_preview.gif.
• outputs/ is generated at runtime and ignored by Git.

To change the working-image limit, set the environment variable before starting the app. For example, in PowerShell:

$env:NEW_LINEART_MAX_SIDE = "1200"
python main_app.py

Or in Bash/Zsh:

NEW_LINEART_MAX_SIDE=1200 python main_app.py

Increasing the limit preserves more small-patch detail but increases memory use and processing time.

Project file summary

new-lineart/
├─ main_app.py               # Current Gradio app and shared processing backend
├─ pyqt_app.py               # PyQt6 desktop UI
├─ frontend/                 # Gradio CSS and Step 2 curve-tool JavaScript
├─ outputs/                  # Runtime PNG/SVG/GIF output; created as needed, Git-ignored
├─ archived_apps/            # Historical prototypes; not supported entry points
├─ core/                     # Legacy/experimental tensor and rendering helpers
├─ utils/                    # Legacy/experimental geometry and artifact-path helpers
├─ artifacts/                # Git-ignored debug, temporary, and legacy run artifacts
├─ wave_flow_simulation/     # Separate Git submodule
├─ install_requirements.py   # Python-version check and pip installer
├─ requirements.txt          # Pinned pip dependency list
├─ environment.yml           # Conda/Mamba definition; Python version currently needs alignment
└─ .gitmodules               # Submodule configuration

The active main_app.py backend currently contains its segmentation, tensor-flow, streamline, export, and animation implementation directly. core/ and utils/ are retained for older prototypes and auxiliary experiments rather than being imported by the active entry points.

Archived apps

Files in archived_apps/ are historical references, not supported entry points. Some of them import removed modules or use older segmentation flows and may not run with the active project tree.

Troubleshooting

The Gradio port is already in use

Set another port before launch. PowerShell example:

$env:GRADIO_SERVER_PORT = "7861"
python main_app.py

Bash/Zsh example:

GRADIO_SERVER_PORT=7861 python main_app.py

Installation fails on the CLIP dependency

Confirm that Git is installed and available in the current shell. requirements.txt installs CLIP from a pinned GitHub commit.

Step 1 detects no patches or merges regions

Use a prepared color-region image with a dark/black background, clear white boundaries, and sufficiently large colored or mid-gray regions. Very small regions may disappear after the working image is resized to the default 800-pixel maximum side.

CPU execution is slow

Lower NEW_LINEART_MAX_SIDE or increase the Step 3 line spacing. Generating many animation frames also increases processing time and disk usage.

中文教學

目前狀態與操作流程

目前專案提供兩個支援的執行入口：

• main_app.py：本機 Gradio Web UI。
• pyqt_app.py：本機 PyQt6 桌面 UI，不會啟動 Web server。

兩個介面共用相同的處理後端，但功能控制並非完全相同：

步驟	Gradio (main_app.py)	PyQt (pyqt_app.py)
Step 1 區域分割	可用；採用規則式色塊 segmentation。	可用；使用相同的色塊分割後端。
Step 2 流向導引	畫筆、橡皮擦，以及前端曲線工具。	畫筆、橡皮擦，以及儲存同心圓中心標記。
Step 3 生成流線	Marker/Hypnotic、指定同心圓 patch、Tensor 預覽、cache 開關、PNG/SVG 下載。	Marker/Hypnotic、指定同心圓 patch、PNG/SVG 儲存。
Step 4 製作動畫	Wave Flow、可指定方向與翻卷強度的 Steam Flow、Adjacent Flow 正向/反向、PNG frames 與 GIF 預覽，或 SVG frames；Wave 可選擇固定端點。	同樣支援 Wave、Steam、Adjacent Flow，並可調整 Steam 翻卷強度。
Step 5 輪廓疊加	可用；可將上傳的輪廓圖疊加到靜態流線，並套用到每個 PNG 動畫 frame，輸出 GIF 預覽與逐幀 ZIP。	可用；支援相同的靜態、GIF 預覽與逐幀 ZIP 合成流程。

Step 3 預覽會暫時畫出 1 px patch 邊界作為整體構圖參考；PNG/SVG 匯出、動畫 frames 與 Step 5 合成使用無 patch 邊界的乾淨流線，最終輪廓由 Step 5 的上傳圖決定。

Step 1 不是 SAM/SAM2 語意分割，而是針對「黑色背景、白色區域邊界、內部為彩色或中灰色色塊」設計的確定性顏色分割流程。目前啟用的 segmentation 不需要模型 checkpoint 或 GPU。

系統需求

• 作業系統：Windows、Linux 或 macOS。
• Python：目前固定版本的 dependency 組合請使用 Python 3.11；其中 scipy==1.16.3 與 scikit-image==0.26.0 都要求 Python 3.11 以上。
• 記憶體：建議 8 GB 以上；圖片越大、流線越密集，所需記憶體與處理時間越高。
• 可使用 CPU 執行；目前啟用的流程不要求 GPU。
• 磁碟空間：需預留 Python 套件以及 PNG、SVG、GIF 輸出空間。

必要與選用工具

• Python 與 pip：執行及安裝專案所需。
• Git：用來 clone repository，也用來安裝 requirements.txt 中以 GitHub commit 固定版本的 CLIP 套件。
• Conda 或 Mamba：選用的環境管理工具，不是唯一安裝方式。
• Gradio：提供本機 Web UI。
• PyQt6：提供桌面 UI。
• NumPy、OpenCV、SciPy、Pillow：目前主要 app 的影像處理與數值運算 runtime。
• 依賴清單也保留歸檔 prototype 與相關專案元件所需的套件。

Clone 專案

若要取得包含 wave_flow_simulation Git submodule 的完整 repository：

git clone --recurse-submodules https://github.com/BobLynn/new-lineart.git
cd new-lineart

如果先前 clone 時沒有下載 submodule：

git submodule update --init --recursive

目前 Gradio 與 PyQt 入口沒有直接 import 此 submodule，但初始化後才是完整的 repository checkout。

安裝環境

選擇下列一種方式即可。

方式一：建立 Python 3.11 Conda 或 Mamba 環境

conda create -n new-lineart python=3.11 pip git
conda activate new-lineart
python install_requirements.py

或：

mamba create -n new-lineart python=3.11 pip git
mamba activate new-lineart
python install_requirements.py

目前 repository 中的 environment.yml 仍指定 Python 3.10，而 install_requirements.py 只會拒絕低於 Python 3.9 的版本；這兩個版本宣告比現有固定 dependency 組合舊，不能代表完整 requirements 相容性。在兩者完成同步前，請依照上方指令明確建立 Python 3.11 環境。

方式二：既有 Python 3.11+ 環境

專案提供的安裝腳本會先檢查 Python 版本，再安裝 requirements.txt：

python install_requirements.py

也可以直接安裝：

python -m pip install -r requirements.txt

你可以使用 venv、Conda、Mamba 或其他環境管理工具。如果終端機找不到 conda activate 或 mamba activate，請先初始化 shell 並重新開啟；例如 Windows PowerShell 使用 conda init powershell，Linux/macOS Bash 使用 conda init bash。

執行 Gradio app

python main_app.py

預設監聽位置：

http://127.0.0.1:7860

可使用以下環境變數修改啟動位置：

• GRADIO_SERVER_NAME，預設 127.0.0.1
• GRADIO_SERVER_PORT，預設 7860

執行 PyQt 桌面版

python pyqt_app.py

PyQt 介面在本機執行，不需要瀏覽器或 Web server。依賴套件安裝完成後，目前的處理流程不需要網路連線。

處理預設值與輸出位置

• NEW_LINEART_MAX_SIDE 限制工作影像最長邊；目前程式碼預設值是 800 pixels。
• 超過限制的圖片會在 segmentation 前等比例縮小，因此輸出使用工作解析度，而不是原始大型圖片的解析度。
• Step 3 線條間距可設為 6–24 pixels，預設 12 pixels。
• Step 4 動畫張數可設為 10–120 frames，兩個 UI 都預設 30 frames。
• Steam Flow 會從所選 patch 的全部原始流線開始，依相鄰關係分組，週期性收束成由各組原線平均而來的窄煙絲並再次展開；風向與風力沿用 Wave Flow 控制，翻卷強度另行調整。
• Step 3 靜態結果會輸出到 outputs/，格式為 PNG 與 SVG。
• 動畫 frames 會輸出到帶有 timestamp 的 outputs/flow_animation_* 資料夾；生成 PNG 動畫時，也會建立 lineart_flow_preview.gif。
• outputs/ 在執行時建立，並已由 Git 忽略。

若要修改工作影像限制，請在啟動 app 前設定環境變數。PowerShell 範例：

$env:NEW_LINEART_MAX_SIDE = "1200"
python main_app.py

Bash/Zsh 範例：

NEW_LINEART_MAX_SIDE=1200 python main_app.py

提高限制可保留更多小 patch 細節，但會增加記憶體使用量與處理時間。

專案檔案簡表

new-lineart/
├─ main_app.py               # 目前的 Gradio app 與共用處理後端
├─ pyqt_app.py               # PyQt6 桌面 UI
├─ frontend/                 # Gradio CSS 與 Step 2 曲線工具 JavaScript
├─ outputs/                  # 執行時 PNG/SVG/GIF 輸出；需要時建立，Git 忽略
├─ archived_apps/            # 歷史 prototypes，不是支援的執行入口
├─ core/                     # 舊版／實驗性 tensor 與 rendering helpers
├─ utils/                    # 舊版／實驗性 geometry 與 artifact path helpers
├─ artifacts/                # Git 忽略的 debug、暫存與舊版執行產物
├─ wave_flow_simulation/     # 獨立 Git submodule
├─ install_requirements.py   # Python 版本檢查與 pip 安裝腳本
├─ requirements.txt          # 固定版本的 pip dependency 清單
├─ environment.yml           # Conda/Mamba 定義；目前 Python 版本仍需同步
└─ .gitmodules               # Submodule 設定

目前啟用的 main_app.py 直接包含 segmentation、tensor flow、streamline、輸出與動畫實作。core/ 與 utils/ 主要保留給舊版 prototypes 與輔助實驗，目前支援的入口沒有 import 它們。

已歸檔 apps

archived_apps/ 中的檔案是歷史參考，不是目前支援的執行入口。部分版本會 import 已移除的模組或使用舊 segmentation 流程，因此未必能在目前 active tree 直接執行。

常見問題

Gradio port 被占用

可在啟動前指定其他 port。PowerShell 範例：

$env:GRADIO_SERVER_PORT = "7861"
python main_app.py

Bash/Zsh 範例：

GRADIO_SERVER_PORT=7861 python main_app.py

CLIP dependency 安裝失敗

確認 Git 已安裝，而且目前 shell 可以找到 git。requirements.txt 會從固定的 GitHub commit 安裝 CLIP。

Step 1 找不到 patch 或把區域合併

請使用深色／黑色背景、清楚白色邊界，以及足夠大的彩色或中灰色區域。原圖若很大，會先縮至預設最長邊 800 pixels，過小區域可能因此消失。

CPU 執行很慢

可降低 NEW_LINEART_MAX_SIDE，或提高 Step 3 線條間距。增加動畫 frames 也會提高處理時間與磁碟使用量。