open-house

A house design project that materializes a simple living lifestyle through programmatic 3D modeling and CAD design.

• Project Overview
• Quick Start
  • Prerequisites
  • Installation
  • Running the Project
• Development Setup
  • Code Quality Tools
  • Available Commands
  • Manual Linting
• 3D Model Features
  • House Structure
  • Architectural Elements
  • 3D Visualization
• Output Files
• Troubleshooting
  • VS Code Viewer Issues
  • Fallback Solution
• Architecture
  • Project Structure
  • Dependencies
• Customization
  • Adjustable Parameters
  • Adding Features
• Contributing
  • Code Standards

Project Overview

This project creates a 3D model of a minimalist house using Python and the build123d library. The house features:

• Dimensions: 10m × 8m × 3m (width × depth × height)
• Wall thickness: 0.3m
• Roof height: 2m with overhang
• Features: Front door, multiple windows, gabled roof

Quick Start

Prerequisites

• Python 3.13+
• uv package manager

Installation

# Clone the repository
git clone https://github.com/marcelovicentegc/simple-living
cd simple-living

# Install dependencies
uv sync

# Install development dependencies (for linting)
uv sync --extra dev

Running the Project

# Run the main application
make dev

# Run with multiple viewer options
make view

# See all available commands
make help

Development Setup

Code Quality Tools

This project includes a comprehensive linting and formatting setup:

• Ruff: Fast Python linter and formatter
• MyPy: Static type checker
• Black: Code formatter
• Pre-commit hooks: Automatic linting on commits

Available Commands

# Development
make dev              # Run the main project (with fallback)
make view             # Run with multiple viewer options
make install-dev      # Install development dependencies

# Code Quality
make lint             # Run all linting checks
make format           # Format code with ruff and black
make check            # Check formatting without fixing
make fix              # Fix auto-fixable linting issues
make clean            # Clean up cache files

# Help
make help             # Show all available commands

Manual Linting

# Run individual tools
uv run ruff check .           # Lint code
uv run ruff format .          # Format code
uv run mypy .                 # Type checking
uv run black .                # Format with black

# Run custom lint script
uv run python lint.py

3D Model Features

House Structure

• Main building: Rectangular base with hollow interior
• Walls: 0.3m thick with proper insulation space
• Floor: Solid base with 0.2m thickness
• Roof: Gabled design with 0.5m overhang

Architectural Elements

• Front door: 1.2m × 2.2m entrance
• Windows: Multiple windows on front and side walls
  • Front facade: 2 windows (1.5m × 1.2m each)
  • Side walls: 4 windows (1.2m × 1.0m each)

3D Visualization

The project supports multiple viewing options:

1. VS Code Extension: Real-time 3D viewing (requires OCP CAD Viewer extension)
2. File Export: Automatic fallback to CAD files
   • .step format: For CAD software (FreeCAD, Fusion 360, etc.)
   • .stl format: For 3D printing (Cura, PrusaSlicer, etc.)

Output Files

When you run the project, it generates:

• minimalist_house.step - CAD format for professional software
• minimalist_house.stl - 3D printing format for manufacturing

Troubleshooting

VS Code Viewer Issues

If you see "Cannot access viewer status" errors:

1. Install the OCP CAD Viewer extension in VS Code
2. Start the viewer from the extension panel
3. Run the project - it should display in VS Code

Fallback Solution

The project automatically handles viewer issues by:

• Detecting when the VS Code viewer isn't available
• Automatically exporting the model to files
• Providing helpful error messages and guidance

Architecture

Project Structure

simple-living/
├── app.py                 # Main application with fallback
├── app_with_viewer.py     # Alternative with multiple viewers
├── lint.py                # Custom linting script
├── Makefile               # Build commands
├── pyproject.toml         # Project configuration
├── .pre-commit-config.yaml # Pre-commit hooks
└── README.md              # This file

Dependencies

• build123d: 3D modeling and CAD operations
• ocp-vscode: VS Code integration for 3D viewing
• Development tools: ruff, mypy, black for code quality

Customization

Adjustable Parameters

You can easily modify the house design by changing these variables in app.py:

house_width = 10      # meters
house_depth = 8       # meters  
house_height = 3      # meters
wall_thickness = 0.3  # meters
roof_overhang = 0.5   # meters
roof_height = 2       # meters

Adding Features

The modular design makes it easy to add:

• Additional rooms
• Different window styles
• Roof variations
• Interior elements

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and ensure they pass linting: make check
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

Code Standards

• All code must pass make check (linting, formatting, type checking)
• Use make fix to automatically fix formatting issues
• Follow the existing code style and patterns