Room Encoding Server

Encode room geometry and parameters into images for daylight prediction models
API Reference · Request Schema
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. API Endpoints
5. Deployment
6. Design
7. Testing
8. Documentation
9. Roadmap
10. Contribution
11. License
12. Contact

About The Project

The Room Encoding Server transforms 3D room geometry and physical parameters into 2D encoded images for use with Daylight Factor (DF) and Daylight Autonomy (DA) prediction models.

Key Features:

• Encode room geometry into NumPy arrays (RGBA images + binary masks)
• Support for single and multi-window rooms with complex polygons
• Automatic facade rotation to align windows to east-facing (0°)
• Direction angle calculated from room polygon (outward-facing)
• Multiple model types: DF/DA with default or custom materials
• Room mask generation (1=room area, 0=background)
• RESTful API with comprehensive validation and error handling
• Object-oriented design following SOLID principles and design patterns

(back to top)

Built With

• Python 3.10+
• Flask - Web framework
• OpenCV - Image processing
• NumPy - Numerical computing
• Shapely - Geometric operations

(back to top)

Getting Started

Prerequisites

• Python 3.10 or higher
• Poetry (recommended) or pip

Installation

Using Poetry (recommended)

1. Clone the repository

   git clone https://github.com/upskiller-xyz/server_encoder.git
   cd server_encoder

2. Install dependencies

   poetry install

3. Activate virtual environment

   poetry shell

4. Run the server

   python -m src.main

Using pip

1. Clone the repository

   git clone https://github.com/upskiller-xyz/server_encoder.git
   cd server_encoder

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Run the server

   python -m src.main

Environment Variables

export PORT=8081  # Default: 8081

(back to top)

Usage

Quick Start

import requests
import numpy as np
import io
import matplotlib.pyplot as plt

url = "http://localhost:8081/encode"

payload = {
    "model_type": "df_default",
    "parameters": {
        "height_roof_over_floor": 2.7,
        "floor_height_above_terrain": 0.0,
        "room_polygon": [[0, 0], [5, 0], [5, 4], [0, 4]],
        "windows": {
            "main_window": {
                "window_sill_height": 0.9,
                "window_frame_ratio": 0.15,
                "x1": -0.6, "y1": 0.0, "z1": 0.9,
                "x2": 0.6, "y2": 0.0, "z2": 2.4,
                "horizon": 15.0,
                "zenith": 10.0
            }
        }
    }
}

response = requests.post(url, json=payload)

# Load NumPy arrays from response
npz_data = np.load(io.BytesIO(response.content))

# Get image and mask (window ID is "main_window")
image = npz_data['main_window_image']  # (128, 128, 4) RGBA
mask = npz_data['main_window_mask']    # (128, 128) binary

# Display
plt.imshow(image)
plt.show()

API Endpoints

GET /

Health check endpoint.

Response:

{
  "status": "running",
  "service": "encoding_service",
  "timestamp": "2025-10-26T12:34:56"
}

POST /encode

Encode room geometry and parameters into NumPy arrays.

Request: JSON with model_type and parameters

Response: NPZ file containing:

• {window_id}_image: (128, 128, 4) RGBA encoded image
• {window_id}_mask: (128, 128) binary room mask (1=room, 0=other)

POST /calculate-direction

Calculate direction angle for windows from room polygon.

Request: JSON with room_polygon and windows (x1, y1, x2, y2 only)

Response: Direction angles in radians and degrees

See API Reference and Room Mask Feature for details.

Model Types

Model Type	Description
df_default	Daylight Factor with default materials (reflectance = 0.8)
da_default	Daylight Autonomy with default materials
df_custom	Daylight Factor with custom material reflectances
da_custom	Daylight Autonomy with custom material reflectances

Multi-Window Support

For rooms with windows on different facades:

payload = {
    "model_type": "df_custom",
    "parameters": {
        "height_roof_over_floor": 2.7,
        "room_polygon": [[0, 0], [5, 0], [5, 4], [0, 4]],
        "windows": {
            "south_window": {
                "x1": -0.6, "y1": 0.0, "z1": 0.9,
                "x2": 0.6, "y2": 0.0, "z2": 2.4,
                # ... other parameters
            },
            "west_window": {
                "x1": 0.0, "y1": -0.5, "z1": 1.0,
                "x2": 0.0, "y2": 0.5, "z2": 2.0,
                # ... other parameters
            }
        }
    }
}

response = requests.post(url, json=payload)
# Returns ZIP file with south_window.png and west_window.png

(back to top)

Deployment

Local Development

export PORT=8081
python -m src.main

Server runs on http://localhost:8081 with debug mode enabled.

Docker

docker build -t room-encoder .
docker run -p 8081:8081 room-encoder

Production

Use a production WSGI server:

gunicorn -w 4 -b 0.0.0.0:8081 src.main:app

(back to top)

Design

Architecture

The server follows strict Object-Oriented Programming principles and design patterns:

Core Components:

ServerApplication
├── EncodingService (handles encoding logic)
│   ├── RoomImageBuilder (constructs images)
│   ├── RoomImageDirector (orchestrates building)
│   └── RegionEncoders (encode specific regions)
│       ├── BackgroundRegionEncoder
│       ├── RoomRegionEncoder
│       ├── WindowRegionEncoder
│       └── ObstructionBarRegionEncoder
├── StructuredLogger (logging system)
└── ServerController (request handling)

Design Patterns Used:

• Builder Pattern: Image construction
• Director Pattern: Orchestration of building process
• Factory Pattern: Encoder and service creation
• Strategy Pattern: Channel mappings, validation rules
• Singleton Pattern: Service instances
• Adapter Pattern: Parameter transformation
• Enumerator Pattern: Constants and magic strings

Principles:

• Single Responsibility Principle (SRP)
• Dependency Injection
• Separation of Concerns
• Type Safety with Type Hints

See CLAUDE.md for detailed development guidelines.

(back to top)

Testing

Run the test suite:

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src --cov-report=html

# Run specific test file
poetry run pytest tests/test_window.py -v

Test Coverage:

• 101 unit tests across 5 test modules
• Coverage for all region encoders
• Validation and integration tests
• Image scaling and positioning tests

(back to top)

Documentation

Comprehensive documentation available in the docs/ directory:

• API Reference - Endpoint documentation and examples
• Request Schema - Complete parameter reference and validation

(back to top)

Roadmap

See the open issues for a full list of proposed features and known issues.

(back to top)

Contribution

Contributions are welcome! Please follow these guidelines:

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Follow the development guidelines in CLAUDE.md
4. Write tests for new functionality
5. Ensure all tests pass: poetry run pytest
6. Commit your Changes using conventional commits
7. Push to the Branch (git push origin feature/AmazingFeature)
8. Open a Pull Request

Development Guidelines:

• Follow Object-Oriented Programming principles
• Use design patterns appropriately
• Add type hints to all functions
• Write self-documenting code
• Update documentation for API changes
• Maintain test coverage above 90%

(back to top)

License

See License for details - GPL-3.0.

Summary: Strong copyleft. You can use, distribute and modify this code in academic and commercial contexts, but you must keep the code open-source under GPL-3.0 and provide appropriate attribution.

(back to top)

Contact

Stanislava Fedorova - stasya.fedorova@gmail.com

Project Link: https://github.com/upskiller-xyz/server_encoder

(back to top)

Acknowledgments

• README template
• Flask - Web framework
• OpenCV - Image processing
• NumPy - Numerical computing
• Shapely - Geometric operations

(back to top)