Skip to content

feat: HD rendering mode and rendering defaults from config file - #23

Open
jonathandip wants to merge 3 commits into
kszenes:masterfrom
jonathandip:master
Open

feat: HD rendering mode and rendering defaults from config file#23
jonathandip wants to merge 3 commits into
kszenes:masterfrom
jonathandip:master

Conversation

@jonathandip

@jonathandip jonathandip commented May 15, 2026

Copy link
Copy Markdown

Inspired by ProteinView's approach to exposing rendering settings, this PR adds a high-definition rendering mode and an optional config file to persist rendering defaults across sessions.

Added

  • --hd flag: start the viewer in HD mode from the command line (moltui file.xyz --hd)
  • H keybinding: toggle HD mode on/off at runtime
  • Atom number labels are rendered directly onto the pixel buffer in HD mode
  • Unsupported terminals show a warning and fall back to braille silently

  • Optional config file at ~/.config/moltui/config.toml to set rendering defaults
  • [rendering] section with configurable ambient, diffuse, specular, shininess, atom_scale, and bond_radius
  • hd = true to start in HD mode by default
  • The --hd CLI flag overrides hd in the config when set
  • Out-of-range values are silently clamped; missing keys fall back to built-in defaults
  • Config loading requires tomllib (Python 3.11+) or tomli; silently skipped if neither is available

Example config

[rendering]
ambient = 0.60
diffuse = 0.70
specular = 0.30
shininess = 48.0
atom_scale = 0.40
bond_radius = 0.10
hd = true

- Move call_after_refresh(_paint_kitty) from _invalidate_cache into
  _rebuild_kitty so the callback fires after the new pixel buffer is
  ready, eliminating the one-keypress display lag in Kitty/FullHD mode.
- Draw atom number labels directly onto the pixel buffer in Kitty mode
  using PIL ImageDraw with a small (9 px) font, matching the #Nums
  toggle that already worked in braille mode.
- Fix APC payload chunking (4096-byte limit with m=1/m=0 continuation)
- Query actual cell pixel dimensions via CSI 16t before app startup;
  drain leftover bytes to avoid polluting Textual's input buffer
- Guard all /dev/tty paths on Windows
- Widen atom-number font fallback to DejaVu (Linux) and load_default()
- Narrow bare except to RuntimeError around call_after_refresh teardown
- Replace auto-activation on mount with opt-in --hd CLI flag and H keybinding
- Rename pixel_mode → hd_mode, action_toggle_pixel_mode → action_toggle_hd_mode
@jonathandip

Copy link
Copy Markdown
Author
image

Adds optional user config at ~/.config/moltui/config.toml with a
[rendering] section covering ambient, diffuse, specular, shininess,
atom_scale, bond_radius, and hd. Missing keys fall back to built-in
defaults; out-of-range values are silently clamped. The --hd CLI flag
overrides config.hd when set.

Note: the hd setting depends on the Kitty HD mode introduced in kszenes#23.
Config loading requires tomllib (Python 3.11+) or tomli; silently
skipped if neither is available.
@jonathandip jonathandip changed the title feat: HD rendering mode via Kitty graphics protocol feat: HD rendering mode and rendering defaults from config file May 15, 2026
@kszenes

kszenes commented May 23, 2026

Copy link
Copy Markdown
Owner

Hi @jonathandip, thanks for the contribution.
In fact, the initial idea for moltui was to use the kitty protocol for viewing the molecules. Unfortunately, I noticed that the performance was a bit choppy, especially through SSH. So I abandoned the idea in favor of Unicode rendering. I tried out your branch and seem to be experiencing similar performance for large systems. Locally, everything seems quite smooth though.
Therefore, I will try to work on improving the performance of the renderer so that this PR could be merged with some quality assurance. I will keep this PR open until I figure out how to mitigate some of the lag that I observe on slower systems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants