Metadata-Version: 2.4
Name: atlas-lattice
Version: 0.1.0
Summary: ATLAS: ASCII Terminal LAttice and Structure viewer — a mini-VESTA in your terminal
Author-email: ooteki-teo <ooteki94@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ooteki-teo/atlas
Project-URL: Repository, https://github.com/ooteki-teo/atlas
Project-URL: Issues, https://github.com/ooteki-teo/atlas/issues
Keywords: crystal,structure,viewer,terminal,ascii,braille,curses,vasp,poscar,cif,xyz,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ATLAS

**ASCII Terminal LAttice and Structure** — a mini-VESTA that lives in your terminal.

ATLAS renders 3D crystal/molecular structures directly in the terminal with
colors, perspective and Braille sub-pixel graphics (2×4 dots per character).
No dependencies beyond the Python standard library (`curses`).

## Features

- 3D structure rendering in pure ASCII/ANSI + Braille sub-pixel mode
  (element colors, depth shading, element labels)
- Mouse: drag to rotate, right-drag to zoom, Shift-drag to pan,
  click an atom for coordinates & bonding info
- World axes (x/y/z) and lattice basis (a/b/c) indicators
- VESTA-style **bond settings**: add/remove/edit per-element-pair rules with
  min/max bond lengths, applied live
- VESTA-style **boundary**: fractional x/y/z ranges to display multiple
  unit cells (with periodic images and inter-cell bonds)
- Auto-rotation animation
- Formats: XYZ / extxyz (with `Lattice`), VASP POSCAR/CONTCAR, CIF (minimal)

## Install

```bash
pip install atlas-lattice
```

From source:

```bash
git clone https://github.com/ooteki-teo/atlas.git
cd atlas
pip install .
```

## Usage

```bash
atlas                 # built-in SrTiO3 demo
atlas POSCAR
atlas caffeine.xyz
python -m atlas_lattice structure.cif
```

Tips: shrink your terminal font size (`⌘-` / `Ctrl-`) for more "pixels".

## Key bindings

| Key | Action |
| --- | --- |
| left-drag | rotate (Shift-drag: pan) |
| right-drag | zoom (alternative to scroll wheel) |
| left-click | select atom, show coordinates / bonding |
| wheel / `+` / `-` / `PgUp` / `PgDn` | zoom (wheel zooms towards cursor) |
| `space` | auto-rotation on/off |
| `b` / `c` / `x` | toggle bonds / cell frame / axes |
| `B` | bond settings dialog (element pairs + length ranges) |
| `v` | boundary dialog (fractional min/max per axis) |
| `g` | toggle Braille high-resolution mode |
| `r` | reset view |
| arrow keys | rotate |
| `q` / `Ctrl-C` | quit (`Esc` only closes dialogs) |

## Examples

Example structures (VASP/CIF) are in [`examples/`](examples/).

## 中文简介

ATLAS 是一个纯终端的晶体/分子结构查看器（"终端版 mini-VESTA"），
支持鼠标旋转缩放、成键规则设置（元素对 + 键长范围）、
多晶胞显示（Boundary 分数坐标范围）、Braille 高分辨率渲染，
仅依赖 Python 标准库。安装：`pip install atlas-lattice`，使用：`atlas POSCAR`。

## License

[MIT](LICENSE)
