Metadata-Version: 2.4
Name: craphics
Version: 0.0.2
Summary: A small Python Library for CPU - rendered graphics
Author: Moinak Debnath
License-Expression: MIT
Project-URL: Homepage, https://github.com/findstring/craphics
Project-URL: Repository, https://github.com/findstring/craphics
Project-URL: Issues, https://github.com/findstring/craphics/issues
Keywords: graphics,cpu,rendering,tkinter,math,shader
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Craphics

A small and lightweight Python 3D graphics module built using Python's standard libraries **`tkinter`**, **`math`**, and **`time`**.

Craphics provides basic 3D rendering with perspective projection, camera movement, mouse-controlled rotation, triangle rendering, and `.obj` model loading.

> **Version:** `v0.0.2`

## Features

* 🖥️ Tkinter-based rendering
* 📐 Basic 3D perspective projection
* 🎥 Movable camera
* 🖱️ Mouse-controlled camera rotation
* 🔺 Triangle-based object rendering
* 📦 Wavefront `.obj` file loading
* 👁️ Near and far rendering planes
* 🎨 Custom object fill and outline colors
* 📊 Optional rendering logs
* ⚙️ Configurable FPS and mouse sensitivity
* 📚 Uses only Python standard libraries
* ✨ Diffuse Shader is applied

## ChangeLog
* Added Diffuse Shader and LIGHT SOURCE

## Installation

Install Craphics using `pip`:

```bash
pip install craphics
```

OR

```bash
pip install craphics==0.0.2
```

## Requirements

Craphics is built using Python's standard library:

* `tkinter`
* `math`
* `time`

No additional Python dependencies are required.

> **Note:** Your Python installation must have Tkinter available.

## Quick Start

```python
import tkinter as tk
from craphics import CRAPHICS

window = tk.Tk()
window.title("Craphics Demo")
window.geometry("800x600")

graphics = CRAPHICS(
    window=window,
    BG="black",
    FOCAL_LENGTH=500,
    CAMERA_DISTANCE=5,
    RENDER_DISTANCE=1000,
    SENSITIVITY=0.005,
	LIGHT_SOURCE=[10,10,-10]
    FPS=60,
    LOG=True
)

window.mainloop()
```

## Controls

| Key / Input  | Action               |
| ------------ | -------------------- |
| `W`          | Move camera forward  |
| `S`          | Move camera backward |
| `A`          | Move camera left     |
| `D`          | Move camera right    |
| `Space`      | Move camera upward   |
| `Left Shift` | Move camera downward |
| Mouse        | Rotate camera        |

The mouse cursor is hidden while using the Craphics canvas.

## API

### `CRAPHICS()`

Creates a Craphics renderer inside the supplied Tkinter window.

```python
CRAPHICS(
    window,
    BG,
    FOCAL_LENGTH,
    CAMERA_DISTANCE,
    RENDER_DISTANCE,
    SENSITIVITY,
	LIGHT_SOURCE,
    FPS,
    LOG
)
```

### Arguments

| Argument          | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `window`          | Tkinter parent window in which the rendering canvas is created    |
| `BG`              | Background color of the rendering canvas                          |
| `FOCAL_LENGTH`    | Focal length used for perspective projection. Must not be `0`     |
| `CAMERA_DISTANCE` | Initial distance of the camera along the Z axis. Must not be `0`  |
| `RENDER_DISTANCE` | Maximum distance from the camera at which objects can be rendered |
| `SENSITIVITY`     | Mouse rotation sensitivity                                        |
| `LIGHT_SOURCE`    | Light source for diffuse shader                                   |
| `FPS`             | Target rendering frames per second. Must be greater than `0`      |
| `LOG`             | If `True`, prints rendering information to the console            |

## Adding Objects

### `add_object()`

Adds a triangle-based 3D object to the scene.

```python
graphics.add_object(
    name,
    fill,
    outline,
    polygons
)
```

### Arguments

| Argument   | Description                               |
| ---------- | ----------------------------------------- |
| `name`     | Unique name used to identify the object   |
| `fill`     | Fill color of the object's triangles      |
| `outline`  | Outline color of the object's triangles   |
| `polygons` | List of triangles that make up the object |

Each triangle consists of three 3D vertices:

```python
polygons = [
    [
        [x1, y1, z1],
        [x2, y2, z2],
        [x3, y3, z3]
    ]
]
```

For example:

```python
triangle = [
    [
        [-1, -1, 0],
        [1, -1, 0],
        [0, 1, 0]
    ]
]

graphics.add_object(
    "Triangle",
    "red",
    "white",
    triangle
)
```

## Removing Objects

### `remove_object()`

Removes an object from the scene using its name.

```python
graphics.remove_object("Triangle")
```

## Loading `.obj` Models

### `add_objfile()`

Craphics can load geometry from a Wavefront `.obj` file.

```python
graphics.add_objfile(
    name,
    fill,
    outline,
    file
)
```

### Arguments

| Argument  | Description                      |
| --------- | -------------------------------- |
| `name`    | Name used to identify the object |
| `fill`    | Fill color of the model          |
| `outline` | Outline color of the model       |
| `file`    | Path to the `.obj` file          |

Example:

```python
graphics.add_objfile(
    "Cube",
    "blue",
    "white",
    "cube.obj"
)
```

### `.obj` Support

The current `.obj` loader supports:

* Vertex definitions (`v`)
* Triangle faces (`f`)
* Vertex/texture/normal face formats such as `f 1/1/1 2/2/2 3/3/3`
* Comments (`#`)
* Vertex normals (`vn`) are ignored

The current implementation expects faces to contain **three vertices**, meaning models should use triangular faces.

## Rendering

Craphics uses a basic perspective projection:

```text
screen_x = FOCAL_LENGTH × x / z
screen_y = FOCAL_LENGTH × y / z
```

Objects are transformed according to the camera's:

* Position
* Yaw
* Pitch

Triangles outside the near and far clipping planes are skipped.

The renderer also performs basic back-face culling, so triangles facing away from the camera are not rendered.

## Camera

The camera starts at:

```python
CAMERA_X = 0
CAMERA_Y = 0
CAMERA_Z = CAMERA_DISTANCE
```

Camera movement is controlled using the keyboard, while yaw and pitch are controlled by mouse movement.

### Camera Parameters

| Parameter         | Description                                        |
| ----------------- | -------------------------------------------------- |
| `CAMERA_DISTANCE` | Initial Z position of the camera                   |
| `SENSITIVITY`     | Amount of camera rotation caused by mouse movement |
| `RENDER_DISTANCE` | Maximum rendering range                            |

## Rendering Logs

Set `LOG=True` to display rendering information:

```python
graphics = CRAPHICS(
    window,
    "black",
    500,
    5,
    1000,
    0.005,
    60,
    True
)
```

The console will display information such as:

```text
[CRAPHICS] Added Object : Cube
[CRAPHICS] Rendered 1 objects | Render time: 2.31 ms | Render FPS: 432.9 | Target FPS: 60
```

Set `LOG=False` to disable these messages.

## Limitations

Craphics is currently intended to be a **simple and experimental 3D renderer**, rather than a full 3D engine.

Current limitations include:

* Triangle-based rendering
* `.obj` faces should be triangles
* No textures
* No lighting system
* No materials
* No shadows
* No perspective-correct texture mapping
* Basic back-face culling
* CPU-based rendering through Tkinter
* Performance decreases with complex models

## Version

**Craphics v0.0.2**

This is an early version of the project and the API may change in future releases.

## License

**MIT License © 2026**

See the `LICENSE` file for the full license text.

---

Made with Python 🐍 and Tkinter.
