sbl-optimizer 0.2.1

Pattern optimizer based on thermal simulations for Swell by Light

🔤 English | 🇯🇵 日本語

sbl-optimizer

Print pattern optimizer for Swell by Light.
Swell by Light (SbL) is an approachable technique for freeform raised textures on paper and other materials. SbL-Optimizer improves print patterns considering heat diffusion, making the resulting swell patterns better match the original images.

Optimization of the printed pattern results in a uniform temperature pattern closely matching the original pattern.

---

Table of Contents

• sbl-optimizer
  • Table of Contents
  • Features
  • Installation
    • 1. (Recommended) From PyPI
    • 2. (Alternative) From Source
    • Requirements
  • Quick Start
  • Command Line Interface
    • Usage
    • Arguments
    • Options
  • Configuration
  • Examples
  • Citation
  • License
• sbl-optimizer 日本語
  • 目次
  • 特徴
  • インストール
    • 1. （推奨）PyPI から
    • 2. ソースから
    • 必要条件
  • クイックスタート
  • コマンドラインインターフェース
    • 使用方法
    • 引数
    • オプション
  • 設定
  • 使用例
  • 引用
  • ライセンス

---

Features

• Adaptive heat‐pattern optimization
  Compensates for heat diffusion to produce raised textures that match your design.
• Simple CLI
  One‐command execution, with JSON‐based configuration and image input.
• Built on Python
  Uses NumPy, Pillow, and Matplotlib for computations and visualizations.

---

Installation

Install sbl-optimizer in two easy ways:

1. (Recommended) From PyPI

pip install sbl-optimizer

2. (Alternative) From Source

Clone the repository and install locally:

git clone https://github.com/sosucat/sbl-optimizer.git
cd sbl-optimizer
pip install .

Requirements

Ensure you have Python and dependencies:

Libraries	Versions
Python	3.9 – 3.11
NumPy	1.24 - 2.2
Pillow	9.5 - 11.x
Matplotlib	3.7 - 3.10

You can also install dependencies manually if they were not installed automatically:

pip install numpy pillow matplotlib

---

Quick Start

1. Run the optimizer with a sample image:

   sbl-optimizer
   

2. Locate the generated optimized pattern sample_opt.pdf in the current directory.

3. Check the simulated temperature distribution sample_temperature.png and swell pattern sample_swell.png.

4. Print the sample_opt.pdf on paper, apply paste, and expose to a strong LED spotlight. Darker printed regions absorb more heat and swell.

5. Try optimizing your own pattern.

   sbl-optimizer path/to/your_image.png
   

---

Command Line Interface

Usage

sbl-optimizer [OPTIONS] <IMAGE>

Arguments

<IMAGE>
Path to the input image (JPG, PNG)

Options

Option	Description
-c, --config <FILE>	Path to JSON config file
-h, --help	Show help message and exit

---

Configuration

Some parameters can be customized via a JSON file (default: config.json shipped with the package).

config.json

{
  "swell_temperature": 145.0,
  "light_power": 100.0,
  "light_diameter": 0.06,
  "alpha": 5e-07,
  "verbose": 1,
  "resolution": 120000
}

Key	Type	Description
swell_temperature	float	Target swelling temperature (°C). Adjust this based on the swell temperature of the paste you have.
light_power	float	Light source power (W). Adjust this according to your light's power.
light_diameter	float	Diameter of the light circle on paper (m). Adjust based on the light circle diameter during heating.
alpha	float	Thermal diffusivity of paper (m²/s).
verbose	int	Bool enabling logging. 0: turned off; 1: turned on.
resolution	int	Number of cells paper is divided into in thermal simulations. Reduce this for faster optimization. Increase for a finer result.

To override defaults:

sbl-optimizer --config path/to/your_config.json <IMAGE>

---

Examples

1. Use default settings on a sample image.

   sbl-optimizer
   

2. Use default settings on your image.

   sbl-optimizer flower.jpg
   

3. Use custom settings

   sbl-optimizer --config my_config.json
   

   , where my_config.json looks like this:

   {
   "swell_temperature": 135.0,
   "light_power": 120.0,
   "light_diameter": 0.07,
   "alpha": 5e-07,
   "verbose": 0,
   "resolution": 50000
   }
   

Output files (in same folder as input image sample.jpg):

File	Description
sample_opt.pdf	Optimized pattern to be printed.
sample_temperature.png	Simulated temperature distribution.
sample_swell.png	Simulated swell pattern.

---

Citation

If you use sbl-optimizer in your research or projects, please cite:

Sosuke Ichihashi, Noura Howell, and HyunJoo Oh. 2025.
Swell by Light: An Approachable Technique for Freeform Raised Textures.
In Proceedings of the Nineteenth International Conference on Tangible, Embedded, and Embodied Interaction (TEI '25). Association for Computing Machinery, New York, NY, USA, Article 45, 1–16. https://doi.org/10.1145/3689050.3704420

@inproceedings{10.1145/3689050.3704420,
author = {Ichihashi, Sosuke and Howell, Noura and Oh, HyunJoo},
title = {Swell by Light: An Approachable Technique for Freeform Raised Textures},
year = {2025},
isbn = {9798400711978},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3689050.3704420},
doi = {10.1145/3689050.3704420},
booktitle = {Proceedings of the Nineteenth International Conference on Tangible, Embedded, and Embodied Interaction},
articleno = {45},
numpages = {16},
keywords = {2.5D fabrication, Personal fabrication, tactile rendering},
location = {Bordeaux / Talence, France},
series = {TEI '25}
}

See the paper and project page for more details.

---

License

This project is licensed under the MIT License.\

---

sbl-optimizer 日本語

Swell by Light (熱光学式2.5次元印刷) 用の印刷パターン最適化ツールです。
Swell by Light は、紙やその他の素材に自由な形のデコボコ模様を作るための手軽な技術です。sbL-optimizer は熱伝導などを考慮して模様の濃淡を調節し、できあがるデコボコ模様を元画像の模様により近づけます。

模様の濃淡の最適化により、元画像の模様に近い均一な温度分布が得られます。

---

目次

• sbl-optimizer
  • Table of Contents
  • Features
  • Installation
    • 1. (Recommended) From PyPI
    • 2. (Alternative) From Source
    • Requirements
  • Quick Start
  • Command Line Interface
    • Usage
    • Arguments
    • Options
  • Configuration
  • Examples
  • Citation
  • License
• sbl-optimizer 日本語
  • 目次
  • 特徴
  • インストール
    • 1. （推奨）PyPI から
    • 2. ソースから
    • 必要条件
  • クイックスタート
  • コマンドラインインターフェース
    • 使用方法
    • 引数
    • オプション
  • 設定
  • 使用例
  • 引用
  • ライセンス

---

特徴

• 熱伝導を考慮した模様最適化
  熱伝導・放射などを考慮し、元画像通りのデコボコ模様ができるように模様の濃淡を調整。
• シンプルなコマンドラインインターフェース (CLI)
  JSON ベースの設定と画像入力でワンコマンド実行。
• Python ベース
  NumPy、Pillow、Matplotlib を使用した計算・可視化。

---

インストール

sbl-optimizer は以下の 2 つの方法でインストールできます。

1. （推奨）PyPI から

pip install sbl-optimizer

2. ソースから

リポジトリをクローンしてローカルにインストールします。

git clone https://github.com/sosucat/sbl-optimizer.git
cd sbl-optimizer
pip install .

必要条件

Python と以下のライブラリが必要です：

ライブラリ	バージョン
Python	3.9 – 3.11
NumPy	1.24 - 2.2
Pillow	9.5 - 11.x
Matplotlib	3.7 - 3.10

自動でインストールされなかった場合は手動でインストールしてください。

pip install numpy pillow matplotlib

---

クイックスタート

1. サンプル画像で最適化を実行します：

   sbl-optimizer
   

2. 現在のディレクトリに生成された最適化された模様 sample_opt.pdf をチェック。

3. シミュレートされた温度分布 sample_temperature.png とデコボコ模様 sample_swell.png をチェック。

4. sample_opt.pdf を印刷し、熱膨張ペーストを塗り、強力な LED スポットライトを照射。模様通りのデコボコが出てきます。

5. 自分の模様画像を最適化してみましょう。

   sbl-optimizer path/to/your_image.png
   

---

コマンドラインインターフェース

使用方法

sbl-optimizer [OPTIONS] <IMAGE>

引数

<IMAGE>
入力画像のパス（JPG, PNG）

オプション

オプション	説明
-c, --config <FILE>	JSON 設定ファイルのパス
-h, --help	ヘルプメッセージを表示して終了

---

設定

一部のパラメータは JSON ファイル（デフォルト：パッケージ付属の config.json）でカスタマイズできます。

config.json

{
  "swell_temperature": 145.0,
  "light_power": 100.0,
  "light_diameter": 0.06,
  "alpha": 5e-07,
  "verbose": 1,
  "resolution": 120000
}

キー	型	説明
swell_temperature	float	膨張温度 [C°]。使用する膨張ペーストに記載されている、ペーストが膨らみ始める温度に応じて調整してください。
light_power	float	光出力 [W]。使用するライトの出力に応じて調節してください。
light_diameter	float	紙面に当たる光の直径 [m]。紙に光を当てて加熱する際に、光が当たる範囲に応じて調整してください。
alpha	float	紙の熱流量 [m²/s]。厚紙や極端に薄い紙などを使用する際に調節してください。
verbose	int	ログ出力の有無。 0：ログなし。 1: ログあり。
resolution	int	熱シミュレーションの解像度。解像度を下げれば、最適化速度が上がる。解像度を上げれば、より画像に忠実なデコボコ模様になる。

カスタム設定で実行するには：

sbl-optimizer --config path/to/your_config.json <IMAGE>

---

使用例

1. サンプル画像をデフォルト設定で最適化

   sbl-optimizer
   

2. 自前の画像をデフォルト設定で最適化

   sbl-optimizer flower.jpg
   

3. サンプル画像をカスタム設定で最適化

   sbl-optimizer --config my_config.json
   

   my_config.json の例：

   {
   "swell_temperature": 135.0,
   "light_power": 120.0,
   "light_diameter": 0.07,
   "alpha": 5e-07,
   "verbose": 0,
   "resolution": 50000
   }
   

出力ファイル（入力画像 sample.jpg と同じフォルダ）：

ファイル名	説明
sample_opt.pdf	印刷用の最適化された模様。
sample_temperature.png	シミュレートされた温度分布。
sample_swell.png	シミュレートされたデコボコ模様。

---

引用

研究やプロジェクトで sbl-optimizer を使用する場合は、以下を引用してください。

Sosuke Ichihashi, Noura Howell, and HyunJoo Oh. 2025.
Swell by Light: An Approachable Technique for Freeform Raised Textures.
In Proceedings of the Nineteenth International Conference on Tangible, Embedded, and Embodied Interaction (TEI '25). Association for Computing Machinery, New York, NY, USA, Article 45, 1–16. https://doi.org/10.1145/3689050.3704420

@inproceedings{10.1145/3689050.3704420,
author = {Ichihashi, Sosuke and Howell, Noura and Oh, HyunJoo},
title = {Swell by Light: An Approachable Technique for Freeform Raised Textures},
year = {2025},
isbn = {9798400711978},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3689050.3704420},
doi = {10.1145/3689050.3704420},
booktitle = {Proceedings of the Nineteenth International Conference on Tangible, Embedded, and Embodied Interaction},
articleno = {45},
numpages = {16},
keywords = {2.5D fabrication, Personal fabrication, tactile rendering},
location = {Bordeaux / Talence, France},
series = {TEI '25}
}

詳細は 論文 および プロジェクトページ を参照してください。

---

ライセンス

このプロジェクトは MIT ライセンス の下で公開されています。