Skip to content

FEAT: Improve fullscreen native image rendering #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merefield merged 1 commit into from
Apr 22, 2026
+401 −19
Merged

FEAT: Improve fullscreen native image rendering #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,8 +105,8 @@ You can set any of these in your shell or `.env` file. `.env` is auto-loaded if
- CLI override: `--lang LANG` applies only to the current run and overrides locale env detection.
- `TERMCOURSE_IMAGES`: Set to `0` to disable inline image previews.
- `TERMCOURSE_IMAGE_BACKEND`: Choose image backend: `auto` (default), `chafa`, `viu`, or `off`.
- `TERMCOURSE_IMAGE_MODE`: Generic image mode for both `chafa` and `viu`: `stable` (default) or `quality`.
- `TERMCOURSE_IMAGE_COLORS`: Chafa quality color mode: `auto` (default), `none`, `16`, `240`, `256`, `full`.
- `TERMCOURSE_IMAGE_MODE`: Image mode preset for `chafa`/`viu`: `compat` (default), `balanced`, or `high`.
- `TERMCOURSE_IMAGE_COLORS`: Chafa `balanced`/`high` color mode: `auto` (default), `none`, `16`, `240`, `256`, `full`.
- `TERMCOURSE_IMAGE_LINES`: Target image preview height in terminal lines (default `14`).
- `TERMCOURSE_IMAGE_DEBUG`: Set to `1` to write image debug logs to `/tmp/termcourse_image_debug.txt`.
- `TERMCOURSE_IMAGE_QUALITY_FILTER`: Set to `0` to allow low-quality blocky previews (default filters them out).
Expand Down Expand Up @@ -182,15 +182,20 @@ Color translation:
## Image Guidelines

- Image previews are shown only for the expanded post in Topic View.
- Fullscreen image view automatically uses native Sixel rendering when the terminal confirms support.
- If `magick` or `convert` is available, fullscreen native rendering uses ImageMagick to resize the source image to the terminal viewport before emitting SIXEL for a larger, more accurate result.
- If ImageMagick is unavailable, fullscreen native rendering falls back to the existing `chafa` SIXEL path.
- If Sixel is unavailable, fullscreen image view falls back to the text-mode renderer.
- Backend selection:
- `TERMCOURSE_IMAGE_BACKEND=auto` tries `chafa` first, then `viu`.
- Set `TERMCOURSE_IMAGE_BACKEND=chafa` or `TERMCOURSE_IMAGE_BACKEND=viu` to force one backend.
- Set `TERMCOURSE_IMAGE_BACKEND=off` or `TERMCOURSE_IMAGES=0` to disable previews.
- Chafa modes:
- `TERMCOURSE_IMAGE_MODE=stable` favors stability and conservative output.
- `TERMCOURSE_IMAGE_MODE=quality` enables higher-detail/color symbol rendering.
- Image modes:
- `TERMCOURSE_IMAGE_MODE=compat` favors stability and conservative output.
- `TERMCOURSE_IMAGE_MODE=balanced` enables higher-detail/color symbol rendering.
- `TERMCOURSE_IMAGE_MODE=high` enables denser symbols and more aggressive chafa tuning for the best text-mode previews.
- Color depth:
- `TERMCOURSE_IMAGE_COLORS=auto` detects terminal support (`truecolor`, `256`, etc.) for chafa quality mode.
- `TERMCOURSE_IMAGE_COLORS=auto` detects terminal support (`truecolor`, `256`, etc.) for chafa balanced/high modes.
- Set `TERMCOURSE_IMAGE_COLORS=full` to force 24-bit if your terminal supports it.
- Height control:
- `TERMCOURSE_IMAGE_LINES` controls preview height (line count), default `14`.
Expand Down
4 changes: 2 additions & 2 deletions lib/termcourse/cli.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,8 +167,8 @@ def help_env_variables
["TERMCOURSE_THEME_FILE", "Theme YAML path. Lookup order: this path, then ./theme.yml, then ~/.config/termcourse/theme.yml."],
["TERMCOURSE_IMAGES", "Set to 0 to disable inline image previews in expanded posts."],
["TERMCOURSE_IMAGE_BACKEND", "Image backend: auto|chafa|viu|off (default: auto)."],
["TERMCOURSE_IMAGE_MODE", "Image mode for chafa/viu: stable|quality (default: stable)."],
["TERMCOURSE_IMAGE_COLORS", "Chafa quality color mode: auto|none|16|240|256|full (default: auto)."],
["TERMCOURSE_IMAGE_MODE", "Image mode preset for chafa/viu: compat|balanced|high (default: compat)."],
["TERMCOURSE_IMAGE_COLORS", "Chafa balanced/high color mode: auto|none|16|240|256|full (default: auto)."],
["TERMCOURSE_IMAGE_LINES", "Target image preview height in terminal lines (default: 14)."],
["TERMCOURSE_IMAGE_DEBUG", "Set to 1 to write image renderer debug logs to /tmp/termcourse_image_debug.txt."],
["TERMCOURSE_IMAGE_QUALITY_FILTER", "Set to 0 to allow low-quality blocky image previews."],
Expand Down
Loading
Loading