133 lines
3.2 KiB
Markdown
133 lines
3.2 KiB
Markdown
# Image Stitcher API by Benscode (Ibnu Fadhil)
|
||
|
||
## Introduction
|
||
|
||
Image Stitcher API is the solution for the Stitch-a-ton Contest by Mas Adin. The implementation emphasizes **correctness**, **performance optimization**, and **code clarity**.
|
||
|
||
---
|
||
|
||
## 1. System Setup and Deployment
|
||
|
||
### Prerequisites
|
||
|
||
- **.NET 8 SDK** or newer.
|
||
|
||
### Development Environment Setup
|
||
|
||
1. **Clone the Repository**
|
||
|
||
```bash
|
||
git clone https://null.formulatrix.dev/benscode/benscode-StitcherApi.git
|
||
cd benscode-StitcherApi
|
||
```
|
||
2. **Configure Image Assets**
|
||
|
||
- Create an `assets` folder in the project root.
|
||
- Place your image tiles in this folder.
|
||
- Optionally set the environment variable `ASSET_PATH_RO` to override the asset path.
|
||
3. **Run the Application**
|
||
|
||
```bash
|
||
dotnet run
|
||
```
|
||
|
||
The API will be hosted locally at:
|
||
|
||
```
|
||
http://localhost:5229
|
||
```
|
||
|
||
### Production Environment Deployment
|
||
|
||
1. **Publish the Application**
|
||
|
||
```bash
|
||
dotnet publish -c Release -r linux-arm64 --self-contained true
|
||
```
|
||
2. **Transfer the publish directory** to the server.
|
||
3. **Configure Asset Path**
|
||
|
||
```bash
|
||
export ASSET_PATH_RO="/path/to/your/image-tiles"
|
||
```
|
||
4. **Execute the Application**
|
||
|
||
```bash
|
||
chmod +x ./StitcherApi
|
||
./StitcherApi
|
||
```
|
||
|
||
---
|
||
|
||
## 2. API Specification
|
||
|
||
**Endpoint:**
|
||
|
||
```
|
||
POST /api/image/generate
|
||
```
|
||
|
||
**Request Body (application/json)**:
|
||
|
||
```json
|
||
{
|
||
"canvas_rect": "A1:H12",
|
||
"crop_offset": [0.25, 0.25],
|
||
"crop_size": [0.5, 0.5],
|
||
"output_scale": 1.0
|
||
}
|
||
```
|
||
|
||
### Parameters
|
||
|
||
- **canvas_rect**: Defines the bounding box of tiles forming the canvas.
|
||
- **crop_offset**: `[x, y]` normalized offset from top-left.
|
||
- **crop_size**: `[width, height]` normalized size relative to the canvas.
|
||
- **output_scale**: Scale factor for the final cropped image.
|
||
|
||
### Responses
|
||
|
||
- **200 OK** – Returns the generated PNG image.
|
||
- **400 Bad Request** – Malformed request or invalid parameters.
|
||
- **404 Not found** - Image not found
|
||
- **500 Internal Server Error** – Unexpected processing error.
|
||
|
||
### **Response Example using Postman**
|
||
|
||
|
||
|
||
---
|
||
|
||
## 3. System Architecture and Logic
|
||
|
||
The system uses a **layered architecture**:
|
||
|
||
- **Program.cs** – Application entry point.
|
||
- **ImageController** – Handles HTTP traffic.
|
||
- **ImageService** – Orchestrates business logic.
|
||
- **Utility classes** – Image parsing and processing.
|
||
|
||
### Core Processing Logic
|
||
|
||
1. **Dimension Calculation**: Compute canvas size without allocating memory.
|
||
2. **Absolute Crop Determination**: Convert normalized crop to pixel coordinates.
|
||
3. **Minimal Tile Selection**: Load only tiles intersecting with the crop.
|
||
4. **Integrated Stitch and Crop**: Copy relevant pixels directly to final canvas.
|
||
5. **Final Scaling and Encoding**: Scale and encode to PNG for the response.
|
||
|
||
**Optimization:**
|
||
|
||
- Avoids creating large intermediate images.
|
||
- Processes one tile at a time for **low memory usage**.
|
||
|
||
---
|
||
|
||
## 4. Performance Analysis
|
||
|
||
- **Time Complexity:** `O(W_crop * H_crop)` Dependent on cropped image size, not full canvas size.
|
||
- **Space Complexity:** `O(W_crop * H_crop + W_tile * H_tile)`
|
||
|
||
- Memory for final image + one 720x720 tile at a time.
|
||
- Predictable and low memory footprint.
|
||
|
||
---
|