Metadata-Version: 2.4
Name: marksgeometrys
Version: 0.2
Summary: Calculate many figures area or volume
Home-page: https://github.com/marc1fino/marksgeometrys
Author: mark. (Marc Pérez)
Author-email: <marcperezcarrasco2010@gmail.com>
License: MIT
Keywords: python,maths,figures,area,volume,mathematical figures
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: summary

# marksgeometrys

A mathematical library for calculating areas and volumes of geometric figures with **unit support**, **numeric returns**, and **proper squared/cubed notation**.

The project provides 24 ready-to-use geometric classes covering 2D shapes (triangles, polygons, circles), 3D solids (prisms, pyramids, platonic solids), and truncated figures — all with configurable units (mm, cm, m, in, ft, etc.) and clean numeric APIs.

**Python** | **Mathematics** | **PyPI**

![Python](https://img.shields.io/badge/Python-3.8+-3776AB?style=flat-square&logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)
![PyPI](https://img.shields.io/badge/PyPI-0.1.1-blue?style=flat-square)
![Dependencies](https://img.shields.io/badge/Dependencies-None-brightgreen?style=flat-square)

## Features

- **24 geometric classes** — from basic 2D shapes to platonic solids and truncated figures
- **Unit-aware calculations** — specify mm, cm, m, in, ft, or any custom unit; squared/cubed notation applied automatically
- **Clean numeric API** — `area()` and `volume()` return `float` values for direct computation
- **Formatted output** — `area_formatted()` and `volume_formatted()` return human-readable strings with units (e.g., `25cm²`, `125m³`)
- **Zero dependencies** — pure Python standard library (`math` only)
- **PyPI ready** — installable via `pip install marksgeometrys`
- **MIT licensed** — free for commercial and educational use

## Shapes

### 2D Figures (Area)

| Class | Parameters | Description |
| :--- | :--- | :--- |
| `Square` | `side` | Square area |
| `Rectangle` | `base`, `height` | Rectangle area |
| `Triangle` | `base`, `height` | Triangle area |
| `RegularPolygon` | `side`, `sidesnumber`, `apothem` | Regular polygon area |
| `Circle` | `radius` | Circle area (πr²) |
| `Trapezoid` | `largebase`, `smallbase`, `height` | Trapezoid area |
| `Rhombus` | `largediagonal`, `smalldiagonal` | Rhombus area |
| `Parallelogram` | `base`, `height` | Parallelogram area |

### 3D Figures (Volume + Surface Area)

| Class | Parameters | Description |
| :--- | :--- | :--- |
| `RegularPolygonPrism` | `side`, `apothem`, `sidesnumber`, `height`, `base` | Prism with regular polygon base |
| `TriangularPrism` | `base`, `theight`, `pheight` | Triangular prism |
| `QuadrangularPrism` | `side1`, `side2`, `height`, `base` | Rectangular-based prism |
| `RectangularPrism` | `side1`, `side2`, `side3`, `height` | Rectangular prism (cuboid) |
| `TrapezoidalPrism` | `largebase`, `smallbase`, `baseheight`, `pheight`, `pbase` | Trapezoidal prism |
| `Sphere` | `radius` | Sphere volume & surface area |
| `Cube` | `side` | Cube volume & surface area |
| `Cylinder` | `radius`, `height` | Cylinder volume & surface area |
| `Pyramid` | `base`, `side`, `sidesnumber`, `apothem`, `side1`, `side2`, `height` | Pyramid with polygon base |
| `Cone` | `radius`, `geometry` (slant height) | Cone volume & surface area |
| `RhomboidalPrism` | `largediagonal`, `smalldiagonal`, `height`, `base` | Rhombus-based prism |

### Platonic Solids

| Class | Parameters | Description |
| :--- | :--- | :--- |
| `Tetrahedron` | `side`, `height` | 4 faces (triangles) |
| `Octohedron` | `side` | 8 faces (triangles) |
| `Dodecahedron` | `side`, `apothem` | 12 faces (pentagons) |
| `Icosahedron` | `side` | 20 faces (triangles) |

### Truncated Figures

| Class | Parameters | Description |
| :--- | :--- | :--- |
| `PyramidTrunk` | `sbside`, `sidesnumber`, `sbapothem`, `lbside`, `lbapothem`, `latlargebase`, `latsmallbase`, `latheight`, `height` | Frustum of a pyramid |
| `ConeTrunk` | `sbradius`, `geometry`, `lbradius`, `height` | Frustum of a cone |

## Quick Start

```bash
pip install marksgeometrys
```

```python
from marksgeometrys import Square, Cube, Octohedron, Sphere

# Numeric returns (float) — ideal for calculations
square = Square(side=5)
print(square.area())              # 25.0

cube = Cube(side=3)
print(cube.volume())              # 27.0
print(cube.area())                # 54.0

# Formatted output with units — ideal for display
print(square.area_formatted())    # "25cm²"
print(cube.volume_formatted())    # "27cm³"

# Custom units (mm, m, in, ft, or any string)
square_mm = Square(side=50, unit="mm")
print(square_mm.area_formatted()) # "2500mm²"

sphere_m = Sphere(radius=0.05, unit="m")
print(sphere_m.volume_formatted()) # "0.0005235987755982989m³"

# Platonic solids (Octohedron bug fixed — now returns values for all sides)
octo = Octohedron(side=4)
print(octo.volume())              # 30.17...
print(octo.area())                # 55.43...
print(octo.volume_formatted())    # "30.17cm³"
```

## Installation

```bash
# From PyPI
pip install marksgeometrys

# From source
git clone https://github.com/marc1fino/marksgeometrys.git
cd marksgeometrys
pip install -e .
```

Requires **Python 3.8+**. Zero external dependencies.

## API Reference

### Core Methods

Every class provides:

| Method | Returns | Description |
| :--- | :--- | :--- |
| `area()` | `float` | Numeric area value |
| `area_formatted()` | `str` | Area with squared unit (e.g., `"25cm²"`) |
| `volume()` | `float` | Numeric volume value (3D shapes only) |
| `volume_formatted()` | `str` | Volume with cubed unit (e.g., `"27cm³"`) |

### Unit Parameter

All classes accept an optional `unit` parameter (default: `"cm"`):

```python
Square(side=5)                    # unit="cm"
Square(side=5, unit="mm")         # millimeters
Square(side=0.05, unit="m")       # meters
Square(side=2, unit="in")         # inches
Square(side=1, unit="ft")         # feet
Square(side=10, unit="px")        # pixels (or any custom string)
```

The unit string is used directly in formatted output — squared for area (`unit²`), cubed for volume (`unit³`).

## Examples

### Basic 2D Calculations

```python
from marksgeometrys import Triangle, Circle, RegularPolygon, Rhombus

triangle = Triangle(base=10, height=6)
print(f"Area: {triangle.area()}")           # 30.0
print(f"Display: {triangle.area_formatted()}") # "30.0cm²"

circle = Circle(radius=7, unit="m")
print(f"Area: {circle.area():.2f} m²")      # 153.94 m²

rhombus = Rhombus(largediagonal=12, smalldiagonal=8, unit="in")
print(rhombus.area_formatted())             # "48.0in²"
```

### 3D Volumes and Surface Areas

```python
from marksgeometrys import Cylinder, Cone, Pyramid, RectangularPrism

cylinder = Cylinder(radius=3, height=10)
print(f"Volume: {cylinder.volume():.2f}")        # 282.74
print(f"Surface: {cylinder.area():.2f}")         # 245.04

cone = Cone(radius=4, geometry=5, unit="ft")  # geometry = slant height
print(cone.volume_formatted())                   # "83.78ft³"
print(cone.area_formatted())                     # "113.10ft²"

# Pyramid with square base
pyramid = Pyramid(
    base=6, side=5, sidesnumber=4, apothem=4,
    side1=6, side2=6, height=8
)
print(pyramid.volume_formatted())                # "96.0cm³"
```

### Platonic Solids

```python
from marksgeometrys import Tetrahedron, Octohedron, Dodecahedron, Icosahedron

tetra = Tetrahedron(side=6, height=5)
print(f"Volume: {tetra.volume():.2f}")    # 25.46
print(f"Area: {tetra.area():.2f}")        # 62.35

octo = Octohedron(side=4)
print(f"Volume: {octo.volume():.2f}")     # 30.17
print(f"Area: {octo.area():.2f}")         # 55.43

dodec = Dodecahedron(side=3, apothem=4.1)
print(dodec.volume_formatted())           # "206.90cm³"

icosa = Icosahedron(side=4)
print(icosa.area_formatted())             # "138.56cm²"
```

### Truncated Figures (Frustums)

```python
from marksgeometrys import PyramidTrunk, ConeTrunk

# Pyramid frustum
trunk = PyramidTrunk(
    sbside=5, sidesnumber=6, sbapothem=4,
    lbside=10, lbapothem=8,
    latlargebase=8, latsmallbase=5, latheight=6,
    height=10
)
print(trunk.volume_formatted())  # "500.0cm³"

# Cone frustum
cone_trunk = ConeTrunk(sbradius=3, geometry=5, lbradius=5, height=10)
print(cone_trunk.volume_formatted())  # "192.68cm³"
```

## Project Structure

```text
marksgeometrys/
├── marksgeometrys/
│   ├── __init__.py          # Exports all classes
│   └── geometry.py          # All 24 geometric classes
├── setup.py                 # PyPI packaging
├── README.md                # This file
└── LICENSE.txt              # MIT License
```

## Requirements

- **Python 3.8+**
- No external dependencies (uses only `math` from standard library)

## Development

```bash
# Clone and install in development mode
git clone https://github.com/marc1fino/marksgeometrys.git
cd marksgeometrys
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\Activate.ps1 on Windows
pip install -e .

# Run tests
python -c "
from marksgeometrys import Square, Cube, Octohedron, Sphere
assert Square(side=5).area() == 25
assert Cube(side=3).volume() == 27
assert Octohedron(side=3).volume() is not None  # Bug fixed
assert Sphere(radius=1).area_formatted().endswith('cm²')
print('All tests passed!')
"
```

## Version History

- **0.1.1** — Current release
  - Numeric returns for `area()` / `volume()`
  - Added `unit` parameter to all classes
  - Added `area_formatted()` / `volume_formatted()` methods
  - Fixed Octohedron returning `None` for non-zero sides
  - Proper squared/cubed unit notation (cm², cm³, mm², m³, etc.)

## Roadmap

- Add perimeter/circumference methods for 2D shapes
- Add moment of inertia calculations for 3D solids
- Support for composite figures
- Spherical coordinates and vector operations
- Type hints and full mypy compatibility
- Comprehensive test suite with pytest

## License

Distributed under the **MIT License**. See [`LICENSE.txt`](LICENSE.txt) for details.

## Author

**Marc Pérez** — [GitHub](https://github.com/marc1fino) | [PyPI](https://pypi.org/project/marksgeometrys/)

---

*Educational mathematics library for students, engineers, and developers.*
