Metadata-Version: 2.4
Name: termux-compass
Version: 0.1.0
Summary: Termux terminal orientation compass and bubble level tools
License: MIT
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown

以下為為 `termux-compass` 專案撰寫的英文 `README.md` 完整內容。您可以直接複製並取代專案根目錄下的 `README.md` 檔案。

---

```markdown
# termux-compass

`termux-compass` is a command-line tool written in Python for Android devices running Termux. It provides a terminal-based directional compass and a bubble level using real-time sensor data provided by the Termux:API.

## Features

- **Compass (`compass-orentation`)**: Interactive directional compass display with customizable visual modes, aspect ratio, and symbols.
- **Bubble Level (`compass-bubble`)**: Real-time terminal pitch and roll visualizer to check surface levelness.
- **Clean Architecture**: Designed following PyPA `src` layout standards with modular sensor streaming logic.

---

## Prerequisites

This package requires an Android device running **Termux** along with the **Termux:API** extension.

1. Install the **Termux:API** app from F-Droid.
2. Install the `termux-api` package in your Termux terminal:

```bash
pkg install termux-api

```

---

## Installation

Install the package directly from PyPI using `pip`:

```bash
pip install termux-compass

```

For local development or editable mode, clone the repository and run:

```bash
pip install -e .

```

---

## Usage

### 1. Orientation Compass

Launch the visual compass by running:

```bash
compass-orentation

```

#### CLI Options

You can customize the compass interface using command-line arguments:

```bash
compass-orentation --mode 16 --symbol "o" --aspect 2

```

Available flags:

* `--config`: Path to custom configuration file (default: `.orienrc`).
* `--width`: Display width in columns, or `auto` (default: `auto`).
* `--radius`: Ring radius, or `auto` to fit terminal bounds (default: `auto`).
* `--thickness`: Ring border thickness in characters.
* `--mode`: Direction cardinal mode (`2`, `4`, `8`, `16`, or `N`/`S`).
* `--aspect`: Character width-to-height ratio to preserve circular shape (default: `2`).
* `--symbol`: Character used to draw the compass ring.

---

### 2. Bubble Level

Launch the terminal bubble level by running:

```bash
compass-bubble

```

The tool renders a centered matrix bubble indicator reflecting device pitch and roll angles in real-time.

---

## Controls

* Press **`q`** at any time while a tool is running to safely exit back to the terminal prompt.
* Press **`Ctrl+C`** to force interrupt.

---

## License

This project is licensed under the MIT License.


