https://github.com/murat65536/dcat
A 3d model viewer for the terminal
https://github.com/murat65536/dcat
3d 3d-engine 3d-graphics 3d-models 3d-viewer 3d-visualization assimp c cli cmake kitty-graphics kitty-graphics-protocol sixel sixel-graphics terminal terminal-app terminal-based terminal-graphics vips vulkan
Last synced: 10 days ago
JSON representation
A 3d model viewer for the terminal
- Host: GitHub
- URL: https://github.com/murat65536/dcat
- Owner: Murat65536
- License: apache-2.0
- Created: 2026-01-19T16:33:26.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-20T00:30:00.000Z (14 days ago)
- Last Synced: 2026-05-20T03:53:12.231Z (14 days ago)
- Topics: 3d, 3d-engine, 3d-graphics, 3d-models, 3d-viewer, 3d-visualization, assimp, c, cli, cmake, kitty-graphics, kitty-graphics-protocol, sixel, sixel-graphics, terminal, terminal-app, terminal-based, terminal-graphics, vips, vulkan
- Language: C
- Homepage:
- Size: 3.69 MB
- Stars: 19
- Watchers: 0
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# dcat
A 3d model viewer for the terminal
https://github.com/user-attachments/assets/ca47ea52-6a46-4ac2-8c9f-430fc9ea9865
## 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](https://mesonbuild.com/) 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):
```sh
# 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:
```sh
# 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](https://www.msys2.org/) 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:
```sh
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:
```sh
# 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`](https://github.com/casey/just), or just run the underlying commands by hand):
```sh
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.