Metadata-Version: 2.4
Name: morphosx
Version: 0.8.0
Summary: high-performance media processing engine for on-the-fly image transformations and storage.
License-Expression: MIT
License-File: LICENSE
Keywords: media,image-processing,cdn,fastapi,bim,ifc,3d,on-the-fly
Author: Davide Di Criscito
Requires-Python: >=3.11,<3.15
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Provides-Extra: 3d
Provides-Extra: bim
Provides-Extra: full
Provides-Extra: modern
Provides-Extra: office
Provides-Extra: pdf
Provides-Extra: raw
Provides-Extra: video
Provides-Extra: vips
Requires-Dist: aioboto3 (>=15.5.0,<16.0.0)
Requires-Dist: aiofiles (>=25.1.0,<26.0.0)
Requires-Dist: fastapi (>=0.132.0,<0.133.0)
Requires-Dist: ffmpeg-python (>=0.2.0,<0.3.0)
Requires-Dist: ffmpeg-python (>=0.2.0,<0.3.0) ; extra == "video"
Requires-Dist: ffmpeg-python ; extra == "full"
Requires-Dist: ifcopenshell (>=0.8.4.post1,<0.9.0) ; extra == "bim"
Requires-Dist: ifcopenshell ; extra == "full"
Requires-Dist: imageio (>=2.37.2,<3.0.0) ; extra == "raw"
Requires-Dist: imageio ; extra == "full"
Requires-Dist: markdown (>=3.10.2,<4.0.0)
Requires-Dist: numpy (<2.0.0) ; extra == "raw"
Requires-Dist: numpy ; extra == "full"
Requires-Dist: openpyxl (>=3.1.5,<4.0.0) ; extra == "office"
Requires-Dist: openpyxl ; extra == "full"
Requires-Dist: passlib[bcrypt] (>=1.7.4,<2.0.0)
Requires-Dist: pillow (>=12.1.1,<13.0.0)
Requires-Dist: pillow-avif-plugin (>=1.5.5,<2.0.0) ; extra == "modern"
Requires-Dist: pillow-avif-plugin ; extra == "full"
Requires-Dist: pillow-heif (>=1.2.1,<2.0.0) ; extra == "modern"
Requires-Dist: pillow-heif ; extra == "full"
Requires-Dist: pydantic-settings (>=2.13.1,<3.0.0)
Requires-Dist: pygltflib (>=1.16.5,<2.0.0) ; extra == "3d"
Requires-Dist: pygltflib ; extra == "full"
Requires-Dist: pygments (>=2.19.2,<3.0.0)
Requires-Dist: pymupdf (>=1.27.1,<2.0.0) ; extra == "pdf"
Requires-Dist: pymupdf ; extra == "full"
Requires-Dist: python-docx (>=1.2.0,<2.0.0) ; extra == "office"
Requires-Dist: python-docx ; extra == "full"
Requires-Dist: python-jose[cryptography] (>=3.5.0,<4.0.0)
Requires-Dist: python-multipart (>=0.0.22,<0.0.23)
Requires-Dist: python-pptx (>=1.0.2,<2.0.0) ; extra == "office"
Requires-Dist: python-pptx ; extra == "full"
Requires-Dist: pyvips (>=3.1.1,<4.0.0) ; extra == "vips"
Requires-Dist: pyvips ; extra == "full"
Requires-Dist: rawpy (>=0.26.1,<0.27.0) ; extra == "raw"
Requires-Dist: rawpy ; extra == "full"
Requires-Dist: trimesh (>=4.11.2,<5.0.0)
Requires-Dist: trimesh (>=4.11.2,<5.0.0) ; extra == "3d"
Requires-Dist: trimesh ; extra == "full"
Requires-Dist: uvicorn (>=0.41.0,<0.42.0)
Description-Content-Type: text/markdown

<p align="center">
  <img src="morphosx-banner.png" alt="morphosx banner" width="600px">
</p>

# morphosx 🧬

> **High performance, low footprint.**  
> Self-hosted, open-source media engine for on-the-fly image processing and delivery.

`morphosx` is a high-speed, minimal cloud storage and media manipulation server. It converts almost any media type into an optimized, web-ready image derivative on-the-fly.

---

## ⚡ Core Features

- **User-Bound Security**: Protected assets and HMAC signatures tied to specific **JWT-authenticated** users.
- **Private Folders**: Secure per-user storage using the `users/{user_id}/` path convention.
- **Universal Rendering**: Support for BIM (IFC), 3D (STL/OBJ/GLB), Office, Font Specimen, Archives, Video, Audio, and RAW.
- **Modern Engines**: Choice between **Pillow** and **PyVips** (ultra-fast).
- **Cloud Ready**: Pluggable storage system (Local & **Amazon S3**).
- **Smart Caching**: Automatic derivative caching for optimized delivery.

---

## 🚀 Installation & Deployment

### 1. Using Docker (Recommended)

The easiest way to run Morphosx with all features and system dependencies pre-installed.

```bash
docker run -p 6100:6100 --env-file .env ghcr.io/dcdavidev/morphosx:latest
```

### 2. Using pip (from PyPI)

You can install Morphosx as a library or a standalone CLI tool.

```bash
# Core installation (standard images only)
pip install morphosx

# Full installation (all media types support)
pip install "morphosx[full]"

# Selective installation
pip install "morphosx[video,pdf,3d]"
```

**Note**: Some extras require system libraries (e.g., `ffmpeg` for video, `libvips` for vips engine).

---

## 📖 Documentation

For detailed guides, check out the `docs/` folder:

- [**Introduction**](docs/introduction.md): Overview, architecture, and quick start.
- [**Upload Guide**](docs/upload.md): Managing public and private asset uploads.
- [**Processing & Presets**](docs/processing.md): On-the-fly transformations and smart presets.
- [**Security & Signatures**](docs/security.md): HMAC validation and asset protection.
- [**Configuration**](docs/configuration.md): Environment variables and server settings.

---

## 🛠️ Usage Guide

### 1. Uploading Assets

**Public Upload**
```bash
curl -X POST "http://localhost:6100/v1/assets/upload?folder=news" -F "file=@img.jpg"
```

**Private Upload**
```bash
curl -X POST "http://localhost:6100/v1/assets/upload?private=true" \
     -H "Authorization: Bearer <TOKEN>" -F "file=@secret.pdf"
```

### 2. Retrieving & Processing

All GET requests must be signed using HMAC-SHA256.

```text
GET /v1/assets/my-image.jpg?width=300&format=webp&signature=HASH
```

---

## ✨ Smart Presets

Use predefined aliases for cleaner URLs:

- `preset=thumb`: 150x150 WebP.
- `preset=hero`: 1920px WebP.
- `preset=social`: 1200x630 JPEG.
- `preset=preview`: 400px PNG.

---

## 🛡️ Advanced Security

Morphosx uses **HMAC-SHA256** to prevent DoS attacks and unauthorized manipulation.
The signature payload includes: `asset_id | width | height | format | quality | preset | user_id`.

---

## 🧪 Supported Media Table

| Category       | Extra      | Extensions          | Output Type            |
| :------------- | :--------- | :------------------ | :--------------------- |
| **BIM**        | `[bim]`    | ifc                 | Technical Project Card |
| **3D**         | `[3d]`     | stl, obj, glb, gltf | Technical Blueprint    |
| **Images**     | Core       | jpg, png, webp      | Processed Image        |
| **Modern Img** | `[modern]` | heic, avif          | Processed Image        |
| **RAW**        | `[raw]`    | cr2, nef, dng, arw  | Developed Image        |
| **Video**      | `[video]`  | mp4, mov, webm, avi | Frame @ timestamp      |
| **Audio**      | `[video]`  | mp3, wav, ogg, flac | Waveform Image         |
| **Docs**       | `[pdf]`    | pdf                 | Page Render            |
| **Office**     | `[office]` | docx, pptx, xlsx    | Summary Card           |
| **Text**       | Core       | json, xml, md, txt  | Syntax-highlighted     |
| **Typography** | Core       | ttf, otf            | Font Specimen          |
| **Archives**   | Core       | zip, tar            | Content List           |

---

## 📜 License

MIT - Built for the Open Source community.


