add readme

README.md

@@ -0,0 +1,133 @@
+# Image Stitcher API by Benscode (Ibnu Fadhi)
+
+## 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 <your-repository-url>
+   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.
+
+---