dcat

A 3d model viewer for the terminal

preview.mp4

Controls

• q - Quit
• m - Toggle wireframe
• Animation controls:
  • p - Play/Pause animation
  • 1 - Previous animation
  • 2 - Next animation
• When FPS controls are enabled:
  • w/a/s/d - Move forward/left/backward/right
  • i/j/k/l - Look around
  • Space - Move up
  • Shift - Move down
  • v - Slow down
  • b - Speed up
• When FPS controls are disabled
  • w/a/s/d - Rotate the camera around the model
  • e/r - Zoom in and out

Character rendering option

• --hash-characters makes character modes (--truecolor-characters, --palette-characters, --block-characters) render with # instead of half-block glyphs.
• In this mode, vertical detail is halved (one source pixel row per terminal row).

Build

This project uses the Meson build system and depends on Vulkan, Assimp, cglm, libvips, and libsixel.

System packages are used by default; the subprojects/*.wrap files are reproducible fallbacks only. cglm is pinned to a hashed wrapdb tarball; assimp, libvips, and libsixel are pinned to immutable git commits. To bump a dependency, change the revision/source_hash in the relevant subprojects/*.wrap and update the accompanying comment. CI builds pass --wrap-mode=nofallback so a missing system dependency fails loudly instead of silently source-building a vendored copy.

Linux

Install the required dependencies (Ubuntu/Debian example):

# Add LunarG Vulkan SDK repository for latest vulkan-headers
wget -qO- https://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo tee /etc/apt/trusted.gpg.d/lunarg.asc
sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-noble.list https://packages.lunarg.com/vulkan/lunarg-vulkan-noble.list
sudo apt-get update

sudo apt-get install -y gcc meson ninja-build libvulkan-dev vulkan-headers shaderc vulkan-utility-libraries-dev libassimp-dev libcglm-dev libsixel-dev pkg-config libvips-dev

Configure and build:

# Release
meson setup build --buildtype=release
meson compile -C build

# Debug
meson setup build-debug --buildtype=debug
meson compile -C build-debug

Windows

On Windows, the project is built using MSYS2 with the clang64 environment. The Windows build uses the bundled libsixel subproject by default to avoid cross-environment pkg-config issues.

1. Install MSYS2.
2. Open the MSYS2 Clang x86_64 terminal.
3. Install dependencies:

pacman -S mingw-w64-clang-x86_64-toolchain mingw-w64-clang-x86_64-meson mingw-w64-clang-x86_64-ninja mingw-w64-clang-x86_64-cmake mingw-w64-clang-x86_64-pkgconf mingw-w64-clang-x86_64-vulkan-headers mingw-w64-clang-x86_64-vulkan-loader mingw-w64-clang-x86_64-shaderc mingw-w64-clang-x86_64-assimp mingw-w64-clang-x86_64-cglm mingw-w64-clang-x86_64-libvips git

Configure and build:

# Release (recommended for installer-bundled DLL distribution)
meson setup build --buildtype=release --default-library=shared -Dbundled_libsixel=enabled
meson compile -C build

# Debug
meson setup build-debug --buildtype=debug -Dbundled_libsixel=enabled
meson compile -C build-debug

When bundled_libsixel is enabled, the bundled libsixel is linked statically on Windows (while other dependencies remain DLL-packaged) to avoid patching upstream libsixel export macros.

Use -Dbundled_libsixel=disabled only if you intentionally want Meson to require a system libsixel package from the active MSYS2 environment.

Windows Notes

• --kitty and --kitty-direct are not supported in native Windows mode.
• Auto-output mode falls back to character rendering modes on Windows.

Development

A justfile provides shortcuts over the Meson commands above (install just, or just run the underlying commands by hand):

just setup-debug   # configure a debug build in ./build
just build         # meson compile -C build
just asan          # debug build with AddressSanitizer + UBSan (b_sanitize)
just devenv        # shell with the built dcat on PATH
just bump-wraps    # refresh subproject sources after editing subprojects/*.wrap

Sanitizer builds use Meson's built-in b_sanitize (e.g. meson setup build -Db_sanitize=address,undefined -Db_lundef=false); no custom option is needed.

meson setup emits build/compile_commands.json. The committed .clangd points clangd at it, so editors get full IntelliSense once any build directory named build is configured.