benscode-StitcherApi/README.md

# 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**

![sample request](image/README/sample_request.jpg)

---

## 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.

---