IFC Processing API

FastAPI for processing IFC (Industry Foundation Classes) using IfcOpenShell.

Documentation

📚 Read the full documentation at louistrue.github.io/openBIM-service

Features

• 🔍 IFC file processing with IfcOpenShell
• 📊 Extract building element properties and quantities
• 🏢 Split IFC files by storey
• 📏 Automatic unit conversion
• 🏗️ Building element information including:
  • Geometry (volume, area, dimensions)
  • Materials and their volumes
  • Properties (loadBearing, isExternal)
  • Building storey assignment
• Process geometry
• Async processing with callback support

Data Privacy & Security

We take data privacy seriously:

• 🗑️ All uploaded files are automatically deleted after processing is complete
• 🧹 Temporary files are completely wiped from container storage every hour
• 🔒 Files are processed with minimal disk persistence
• 📝 Processing logs are kept only for debugging and are regularly purged
• 🔐 All API requests require authentication via API key

Prerequisites

• Python 3.10+
• pip

Installation

1. Clone the repository:

git clone <repository-url>
cd <repository-name>

2. Create and activate virtual environment:

python -m venv venv
source venv/bin/activate  # Linux/Mac
.\venv\Scripts\activate   # Windows

3. Install dependencies:

pip install -r requirements.txt
pip install -r requirements-dev.txt  # For development

4. Set up your API key:

Create a .env file in the project root:

API_KEY=your-api-key-here

This API key is required for all API requests and tests.

Development

Start the development server:

python run.py

The API will be available at http://localhost:8000

Testing

Run tests using pytest:

# Run all tests
pytest

# Run with coverage report
pytest --cov=app tests/

# Run specific test file
pytest tests/test_endpoints.py

Test outputs are saved in tests/output/ directory, including:

• Process results in JSONL format
• Error responses in JSON format

Project Structure

app/
├── main.py              # FastAPI application entry point
├── api/
│   ├── routes/
│   │   └── ifc_routes.py # API endpoints
├─ core/
│   ├── config.py        # Application settings
│   ├── security.py      # API key authentication & rate limiting
│   └── models/          # Pydantic data models
│       └── ifc.py       # IFC-related data models
└── services/
    ├── ifc/            # IFC processing services
    │   ├── properties.py  # Element property extraction
    │   ├── quantities.py  # Geometric quantities
    │   ├── splitter.py    # IFC model splitting
    │   └── units.py       # Unit conversion utilities
    └─ lca/            # Life Cycle Assessment
        └── materials.py   # Material processing
tests/
├── conftest.py         # Pytest configuration
├── test_endpoints.py   # API tests
└── output/            # Test results and logs

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to:

• Set up your development environment
• Follow our code style guidelines
• Submit pull requests
• Report issues

By contributing, you agree that your contributions will be licensed under the AGPL-3.0 License.

Credits

This project is built on top of several excellent open-source projects:

• IfcOpenShell - The core IFC processing library (LGPL-3.0)
• FastAPI - Modern web framework for building APIs (MIT)
• Pydantic - Data validation using Python type annotations (MIT)
• pytest - Testing framework (MIT)
• uvicorn - Lightning-fast ASGI server (BSD-3-Clause)

Special thanks to:

• The IfcOpenShell community for their excellent IFC processing tools and documentation
• All contributors to the dependencies that make this project possible

Callback Functionality

The /api/ifc/extract-building-elements endpoint supports asynchronous processing with callbacks. When using callbacks:

1. The endpoint returns immediately with a task ID
2. Progress updates (10%) are sent to the callback URL
3. Final results are sent to the callback URL
4. All callback requests include the provided token in Authorization header

Callback Data Format

Progress updates:

{
  "status": "processing",
  "progress": 10,
  "total_elements": 100,
  "processed_elements": 10
}

Final result:

{
    "status": "completed",
    "progress": 100,
    "result": {
        "metadata": { ... },
        "elements": [ ... ]
    }
}

Error case:

{
  "status": "error",
  "error": "Error message"
}

Testing Callbacks

1. Start the callback test server:

python tests/callback_server.py

2. In another terminal, run the test script:

python tests/test_callback.py

The callback server will log all received callbacks, including progress updates and the final result.