Metadata-Version: 2.4
Name: crypto-3d
Version: 1.0.0
Summary: Esfera 3D de caracteres en terminal con precios en vivo de Bitcoin, Ethereum y Litecoin
Author-email: Gilbert Perez <artelove07@gmail.com>
License: MIT
Keywords: bitcoin,ethereum,litecoin,ascii-art,terminal,crypto
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=12.0.0
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# 🔮 Crypto 3D Sphere Terminal (`crypto-3d`)

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.7+-green.svg)

Aplicación para terminales (Windows, macOS, Linux) que muestra **esferas 3D
volumétricas en tiempo real, dibujadas como ASCII art a color**, con
**logotipos en relieve proyectados sobre la superficie curva**, **iluminación
física Blinn-Phong**, **transiciones degradadas suaves (morph/cross-dissolve)**
y datos de mercado en vivo para **Bitcoin (BTC)**, **Ethereum (ETH)** y
**Litecoin (LTC)**.

La escena se sombrea como una imagen RGB real y luego se resuelve a caracteres
sueltos sobre negro. Dos canales llevan la imagen: la **densidad** sostiene la
silueta (la cara oscura pierde glifos, la iluminada los agolpa) y el **color**
separa cuerpo de emblema — la esfera va teñida y tenue, el logo va blanco.
Los glifos están anclados a la superficie, así que viajan con el giro en lugar
de quedarse como una rejilla fija.

---

## 🌟 Características

| Característica | Descripción |
|---|---|
| 🔠 **Esfera de caracteres** | Dígitos sueltos sobre negro: la forma sale de cuántos sobreviven y de su brillo, no de un degradado de símbolos. El fondo son espacios, así que la esfera flota en tu terminal en vez de vivir dentro de un rectángulo pintado |
| 🌐 **Esfera volumétrica por trazado de rayos** | Intersección analítica rayo–esfera y normal 3D por píxel, con corrección de la relación de aspecto de la celda del terminal |
| 💎 **Logos vectoriales con relieve real** | Cada marca se hornea como campo de distancia con signo y biselado; su gradiente perturba la normal (*bump mapping*), así que el logo capta su propio brillo especular en vez de ser una mancha de color |
| 🪙 **Grabado en las dos caras** | Cada moneda lleva el logo en ambos polos: al girar, la marca vuelve dos veces por vuelta en lugar de desaparecer media rotación |
| ✨ **Iluminación de estudio** | Luz principal + relleno + reflejo especular Blinn-Phong + borde Fresnel + reflexión de entorno con horizonte y tono fílmico ACES |
| 🔄 **Transición degradada** | Disolución cruzada de texturas y color que **viaja por la rueda cromática** con un destello metálico a mitad de camino, en vez de pasar por un marrón muerto |
| 📈 **Precios y métricas en vivo** | CoinGecko en hilo aparte: la red nunca bloquea un fotograma |
| 📊 **Ticker de las tres monedas** | BTC, ETH y LTC a la vez, con la activa resaltada |
| 🖥️ **Adaptativo** | El tamaño de la esfera se ajusta al alto del terminal; la animación va por reloj, así que la velocidad es la misma a 12 o a 60 FPS |
| 🚀 **Sin dependencias de cálculo** | Todo en Python puro: solo `rich` y `requests` |

---

## 🚀 Instalación y Uso Rápido

> **Todavía no está publicado en PyPI.** El nombre `crypto-3d` está libre, así
> que `pip install crypto-3d` hoy falla con 404. Usa la instalación local.

### Opción 1: Instalación local como comando global
Desde la carpeta del proyecto:
```bash
pip install -e .
```
Eso deja disponibles `crypto3d`, `crypto-3d` y `btc3d` en cualquier terminal.

---

### Opción 2: Ejecución directa
1. Instala las dependencias:
   ```bash
   pip install -r requirements.txt
   ```
   o
   ```bash
   pip install rich requests
   ```

2. Ejecuta la aplicación:
   ```bash
   python -m crypto_3d.cli
   ```
   o en Windows con el archivo `.bat`:
   ```cmd
   crypto3d.bat
   ```

---

## ⚙️ Argumentos de Línea de Comandos

| Argumento | Alias | Descripción | Ejemplo |
|---|---|---|---|
| `--coin` | `-c` | Empieza en una moneda concreta | `crypto3d --coin eth` |
| `--fps` | `-f` | Fotogramas por segundo objetivo (1–60, por defecto 24) | `crypto3d --fps 30` |
| `--rows` | `-r` | Alto de la esfera en filas (por defecto: según el terminal) | `crypto3d --rows 18` |
| `--cell-aspect` | | Alto/ancho de la celda del terminal, por defecto 2.0 | `crypto3d --cell-aspect 1.85` |
| `--glyphs` | `-g` | Caracteres de la esfera: `digits`, `hex`, `binary` o `ticker` | `crypto3d -g hex` |
| `--static` | `-s` | Sin rotación | `crypto3d --static` |
| `--freeze` | | Se queda en una moneda, sin ciclar | `crypto3d -c btc --freeze` |
| `--no-donations` | | Oculta las direcciones de tips | `crypto3d --no-donations` |

### Ejemplos
```bash
crypto3d --coin eth --fps 30
```

```bash
crypto3d -c ltc --freeze
```

### Si la esfera no sale redonda

Depende de la relación alto/ancho de la celda de tu terminal. Windows Terminal
y la mayoría de fuentes monoespaciadas están cerca de 2.0, que es el valor por
defecto. Si la ves **achatada**, sube el valor; si la ves **estirada**, bájalo:

```bash
crypto3d --cell-aspect 1.85
```

### Tamaño de terminal

**Maximiza la ventana.** La esfera se dimensiona a lo que quede libre, así que
el tamaño del terminal es lo que decide la resolución:

| Terminal | Esfera | Columnas laterales | Donaciones |
|---|---|---|---|
| 60×24 | 22×11 | no caben | no caben |
| 80×28 | 36×18 | sí | no caben |
| 120×40 | 50×25 | sí | sí |
| 160×50 | 70×35 | sí | sí |
| 200×60 | 90×45 | sí | sí |

A partir de unas 72 columnas el ticker y las cifras de 24 h se mueven a dos
columnas laterales junto a la esfera: eso llena el hueco y devuelve tres filas
a la animación. Por debajo vuelven a apilarse debajo, porque las columnas
ahogarían la esfera. Si el alto no da para una esfera legible, el bloque de
donaciones se retira solo y le cede sus filas. Si redimensionas la ventana en
marcha, todo se recalcula al vuelo.

---

## 🛠️ Añadir al PATH de Windows (Atajo Global Local)

Para escribir `crypto3d` desde cualquier carpeta sin instalar desde PyPI:

1. Abre el Símbolo del Sistema (CMD) como Administrador.
2. Ejecuta:
   ```cmd
   setx PATH "%PATH%;C:\Ruta\A\Tu\Carpeta"
   ```

---

## ☕ Donaciones

Si te gusta el proyecto y deseas apoyar su desarrollo:

| Criptomoneda | Dirección |
|---|---|
| ₿ **Bitcoin (BTC)** | `bc1q54wksh4fqhcfdwmlvp9x6g4wzgqt3u2kxds33c` |
| Ξ **Ethereum (ETH)** | `0x94e0eb2b6f30c5e41Df5bb60Ad24Df3B2C58C9bd` |
| Ł **Litecoin (LTC)** | `ltc1qcfwweu62kee4y42r34kj7fpqa39xya5zjk9y6v` |

*Made with love for my crypto bros ❤️*

---

## 📄 Licencia

MIT License © 2026
