# sbl-optimizer
[](https://doi.org/10.1145/3689050.3704420)
[](https://badge.fury.io/py/sbl-optimizer)
[](https://github.com/sosucat/sbl-optimizer)
[](https://github.com/sosucat/sbl-optimizer)\
[](https://sites.gatech.edu/futurefeelings/2025/03/07/swell-by-light-tei-25/)
[](https://sosuke-ichihashi.com/)
[](https://doi.org/10.1145/3689050.3704420)
[](https://youtu.be/LomVS_jHxl0?feature=shared)
Print pattern optimizer for ``Swell by Light (SbL)``.\
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](#sbl-optimizer)
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Installation](#installation)
- [1. (Recommended) From PyPI](#1-recommended-from-pypi)
- [2. From Source](#2-from-source)
- [Requirements](#requirements)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Command Line Interface](#command-line-interface)
- [Usage](#usage)
- [Arguments](#arguments)
- [Options](#options)
- [Examples](#examples)
- [Citation](#citation)
- [Contributing](#contributing)
- [License](#license)
---
## 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
```bash
pip install sbl-optimizer
```
### 2. From Source
Clone the repository and install locally:
```bash
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:
```bash
pip install numpy pillow matplotlib
```
---
## Quick Start
1. Run the optimizer with a sample image:
```bash
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.
```bash
sbl-optimizer path/to/your_image.png
```
---
## Configuration
Some parameters can be customized via a JSON file (default: `config.json` shipped with the package).
`config.json`
```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:
```bash
sbl-optimizer --config path/to/your_config.json <IMAGE>
```
---
## Command Line Interface
### Usage
```bash
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 |
---
## Examples
1. Use default settings on a sample image.
```bash
sbl-optimizer
```
2. Use default settings on your image.
```bash
sbl-optimizer flower.jpg
```
3. Use custom settings
```bash
sbl-optimizer --config my_config.json
```
, where ``my_config.json`` looks like this:
```json
{
"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
```bibtex
@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](https://doi.org/10.1145/3689050.3704420) and [project page](https://sites.gatech.edu/futurefeelings/2025/03/07/swell-by-light-tei-25/) for more details.
---
## Contributing
Contributions, issues, and feature requests are welcome!
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/foo`)
3. Commit your changes (`git commit -am 'Add foo'`)
4. Push to the branch (`git push origin feature/foo`)
5. Open a Pull Request
Please follow the existing code style and write tests for new functionality.
---
## License
This project is licensed under the [MIT License](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "sbl-optimizer",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.9",
"maintainer_email": "Sosuke Ichihashi <pengu1n.i843@gmail.com>",
"keywords": "hci, fabrication, diy, swell by light, heat transfer",
"author": null,
"author_email": "Sosuke Ichihashi <pengu1n.i843@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7d/bc/114b4963697b626e0ed8dc7e43771952eda3f8c4092b64ae88304aa34885/sbl_optimizer-0.1.6.tar.gz",
"platform": null,
"description": "# sbl-optimizer\r\n\r\n[](https://doi.org/10.1145/3689050.3704420)\r\n[](https://badge.fury.io/py/sbl-optimizer)\r\n[](https://github.com/sosucat/sbl-optimizer)\r\n[](https://github.com/sosucat/sbl-optimizer)\\\r\n[](https://sites.gatech.edu/futurefeelings/2025/03/07/swell-by-light-tei-25/)\r\n[](https://sosuke-ichihashi.com/)\r\n[](https://doi.org/10.1145/3689050.3704420)\r\n[](https://youtu.be/LomVS_jHxl0?feature=shared)\r\n\r\n\r\n\r\nPrint pattern optimizer for ``Swell by Light (SbL)``.\\\r\nSbL 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.\r\n\r\n\r\nOptimization of the printed pattern results in a uniform temperature pattern closely matching the original pattern.\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n- [sbl-optimizer](#sbl-optimizer)\r\n - [Table of Contents](#table-of-contents)\r\n - [Features](#features)\r\n - [Installation](#installation)\r\n - [1. (Recommended) From PyPI](#1-recommended-from-pypi)\r\n - [2. From Source](#2-from-source)\r\n - [Requirements](#requirements)\r\n - [Quick Start](#quick-start)\r\n - [Configuration](#configuration)\r\n - [Command Line Interface](#command-line-interface)\r\n - [Usage](#usage)\r\n - [Arguments](#arguments)\r\n - [Options](#options)\r\n - [Examples](#examples)\r\n - [Citation](#citation)\r\n - [Contributing](#contributing)\r\n - [License](#license)\r\n\r\n---\r\n\r\n## Features\r\n\r\n- **Adaptive heat\u2010pattern optimization** \r\n Compensates for heat diffusion to produce raised textures that match your design.\r\n- **Simple CLI** \r\n One\u2010command execution, with JSON\u2010based configuration and image input.\r\n- **Built on Python** \r\n Uses NumPy, Pillow, and Matplotlib for computations and visualizations.\r\n\r\n---\r\n\r\n## Installation\r\nInstall `sbl-optimizer` in two easy ways:\r\n\r\n### 1. (Recommended) From PyPI\r\n\r\n```bash\r\npip install sbl-optimizer\r\n```\r\n\r\n### 2. From Source\r\nClone the repository and install locally:\r\n\r\n```bash\r\ngit clone https://github.com/sosucat/sbl-optimizer.git\r\ncd sbl-optimizer\r\npip install .\r\n```\r\n\r\n### Requirements\r\n\r\nEnsure you have Python and dependencies:\r\n| Libraries | Versions |\r\n| ---------- | ---------- |\r\n| Python | 3.9 \u2013 3.11 |\r\n| NumPy | 1.24 - 2.2 |\r\n| Pillow | 9.5 - 11.x |\r\n| Matplotlib | 3.7 - 3.10 |\r\n\r\nYou can also install dependencies manually if they were not installed automatically:\r\n\r\n```bash\r\npip install numpy pillow matplotlib\r\n```\r\n---\r\n\r\n## Quick Start\r\n\r\n1. Run the optimizer with a sample image:\r\n\r\n ```bash\r\n sbl-optimizer\r\n ```\r\n\r\n2. Locate the generated optimized pattern `sample_opt.pdf` in the current directory.\r\n\r\n3. Check the simulated temperature distribution `sample_temperature.png` and swell pattern `sample_swell.png`.\r\n\r\n4. Print the `sample_opt.pdf` on paper, apply paste, and expose to a strong LED spotlight. Darker printed regions absorb more heat and swell.\r\n\r\n5. Try optimizing your own pattern.\r\n \r\n ```bash\r\n sbl-optimizer path/to/your_image.png\r\n ```\r\n\r\n---\r\n\r\n## Configuration\r\n\r\nSome parameters can be customized via a JSON file (default: `config.json` shipped with the package).\r\n\r\n`config.json`\r\n```json\r\n{\r\n \"swell_temperature\": 145.0,\r\n \"light_power\": 100.0,\r\n \"light_diameter\": 0.06,\r\n \"alpha\": 5e-07,\r\n \"verbose\": 1,\r\n \"resolution\": 120000\r\n}\r\n```\r\n\r\n| Key | Type | Description |\r\n|---------------------|--------|---------------------------------------------------------------|\r\n| `swell_temperature` | float | Target swelling temperature (\u00b0C). Adjust this based on the swell temperature of the paste you have. |\r\n| `light_power` | float | Light source power (W). Adjust this according to your light's power. |\r\n| `light_diameter` | float | Diameter of the light circle on paper (m). Adjust based on the light circle diameter during heating. |\r\n| `alpha` | float | Thermal diffusivity of paper (m\u00b2/s). |\r\n| `verbose` | int | Bool enabling logging. 0: turned off; 1: turned on. |\r\n| `resolution` | int | Number of cells paper is divided into in thermal simulations. Reduce this for faster optimization. Increase for a finer result.|\r\n\r\nTo override defaults:\r\n\r\n```bash\r\nsbl-optimizer --config path/to/your_config.json <IMAGE>\r\n```\r\n\r\n---\r\n\r\n## Command Line Interface\r\n\r\n### Usage\r\n\r\n```bash\r\nsbl-optimizer [OPTIONS] <IMAGE>\r\n```\r\n\r\n### Arguments\r\n\r\n `<IMAGE>`\\\r\n Path to the input image (JPG, PNG)\r\n\r\n### Options\r\n\r\n| Option | Description |\r\n| ----------------------- | -------------------------- |\r\n| `-c`, `--config <FILE>` | Path to JSON config file |\r\n| `-h`, `--help` | Show help message and exit |\r\n\r\n---\r\n\r\n## Examples\r\n\r\n1. Use default settings on a sample image.\r\n ```bash\r\n sbl-optimizer\r\n ```\r\n\r\n2. Use default settings on your image.\r\n ```bash\r\n sbl-optimizer flower.jpg\r\n ```\r\n\r\n3. Use custom settings\r\n ```bash\r\n sbl-optimizer --config my_config.json\r\n ```\r\n , where ``my_config.json`` looks like this:\r\n ```json\r\n {\r\n \"swell_temperature\": 135.0,\r\n \"light_power\": 120.0,\r\n \"light_diameter\": 0.07,\r\n \"alpha\": 5e-07,\r\n \"verbose\": 0,\r\n \"resolution\": 50000\r\n }\r\n ```\r\n\r\nOutput files (in same folder as input image `sample.jpg`):\r\n\r\n| File | Description |\r\n| ------------------------- | ----------------------------------- |\r\n| `sample_opt.pdf` | Optimized pattern to be printed. |\r\n| `sample_temperature.png` | Simulated temperature distribution. |\r\n| `sample_swell.png` | Simulated swell pattern. |\r\n\r\n---\r\n\r\n## Citation\r\n\r\nIf you use **sbl-optimizer** in your research or projects, please cite:\r\n\r\nSosuke Ichihashi, Noura Howell, and HyunJoo Oh. 2025.\\\r\nSwell by Light: An Approachable Technique for Freeform Raised Textures. \\\r\nIn 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\u201316. https://doi.org/10.1145/3689050.3704420\r\n\r\n```bibtex\r\n@inproceedings{10.1145/3689050.3704420,\r\nauthor = {Ichihashi, Sosuke and Howell, Noura and Oh, HyunJoo},\r\ntitle = {Swell by Light: An Approachable Technique for Freeform Raised Textures},\r\nyear = {2025},\r\nisbn = {9798400711978},\r\npublisher = {Association for Computing Machinery},\r\naddress = {New York, NY, USA},\r\nurl = {https://doi.org/10.1145/3689050.3704420},\r\ndoi = {10.1145/3689050.3704420},\r\nbooktitle = {Proceedings of the Nineteenth International Conference on Tangible, Embedded, and Embodied Interaction},\r\narticleno = {45},\r\nnumpages = {16},\r\nkeywords = {2.5D fabrication, Personal fabrication, tactile rendering},\r\nlocation = {Bordeaux / Talence, France},\r\nseries = {TEI '25}\r\n}\r\n```\r\n\r\nSee the [paper](https://doi.org/10.1145/3689050.3704420) and [project page](https://sites.gatech.edu/futurefeelings/2025/03/07/swell-by-light-tei-25/) for more details.\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nContributions, issues, and feature requests are welcome! \r\n1. Fork the repository \r\n2. Create a feature branch (`git checkout -b feature/foo`) \r\n3. Commit your changes (`git commit -am 'Add foo'`) \r\n4. Push to the branch (`git push origin feature/foo`) \r\n5. Open a Pull Request\r\n\r\nPlease follow the existing code style and write tests for new functionality.\r\n\r\n---\r\n\r\n## License\r\n\r\nThis project is licensed under the [MIT License](LICENSE).\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Thermal swell pattern optimizer for Swell by Light",
"version": "0.1.6",
"project_urls": {
"Author": "https://sosuke-ichihashi.com/",
"HomePage": "https://sites.gatech.edu/futurefeelings/2025/03/07/swell-by-light-tei-25/",
"Paper": "https://dl.acm.org/doi/10.1145/3689050.3704420",
"Repository": "https://github.com/sosucat/sbl-optimizer"
},
"split_keywords": [
"hci",
" fabrication",
" diy",
" swell by light",
" heat transfer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "885a51d5e9753f2e92c74e64c5723cbdaf76e7171d9e279f5daf2d650ba6aad5",
"md5": "16a71e039a4db656884e8f64366a8ae0",
"sha256": "b7d51d10758efbf2da895d17cd0bbfc1900522c4cf38eee7ebc4ae98f590e098"
},
"downloads": -1,
"filename": "sbl_optimizer-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "16a71e039a4db656884e8f64366a8ae0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.9",
"size": 108994,
"upload_time": "2025-07-31T05:17:58",
"upload_time_iso_8601": "2025-07-31T05:17:58.011663Z",
"url": "https://files.pythonhosted.org/packages/88/5a/51d5e9753f2e92c74e64c5723cbdaf76e7171d9e279f5daf2d650ba6aad5/sbl_optimizer-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7dbc114b4963697b626e0ed8dc7e43771952eda3f8c4092b64ae88304aa34885",
"md5": "166ceec3cf10539e2c8568421cc5f185",
"sha256": "bfffe3b9fb5d1a3fc88d3ab119d18fed50eea01f9b4f7878a5524b3f659e85e9"
},
"downloads": -1,
"filename": "sbl_optimizer-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "166ceec3cf10539e2c8568421cc5f185",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.9",
"size": 110987,
"upload_time": "2025-07-31T05:17:59",
"upload_time_iso_8601": "2025-07-31T05:17:59.578376Z",
"url": "https://files.pythonhosted.org/packages/7d/bc/114b4963697b626e0ed8dc7e43771952eda3f8c4092b64ae88304aa34885/sbl_optimizer-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 05:17:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sosucat",
"github_project": "sbl-optimizer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sbl-optimizer"
}
JSON
