roomrubikspack 0.1.0__tar.gz

roomrubikspack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vijesh Kumar V
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

roomrubikspack-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: roomrubikspack
+Version: 0.1.0
+Summary: Client wrapper for procedural architectural floorplan layout generator
+Author-email: Vijesh Kumar V <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/roomrubikspack
+Project-URL: Bug Tracker, https://github.com/yourusername/roomrubikspack/issues
+Keywords: architecture,floorplan,layout,genetic-algorithm,CAD,procedural
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: networkx>=2.6.0
+Requires-Dist: ezdxf>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# RoomRubiksPack (Client Library)
+
+RoomRubiksPack is a lightweight Python package for generating architectural floorplan layouts using procedural generation and an Elitist Genetic Algorithm. 
+
+This client library maintains a local, stateful API for creating room models, local graphing/connectivity check, local plotting/visualisation via `matplotlib`, and local CAD exports via `ezdxf`. The computationally heavy layout generation (GA) and auto-dimensioning are offloaded to a RoomRubiks API Server.
+
+---
+
+## Installation
+
+### Option 1: Install from PyPI
+Once published, install the package via:
+```bash
+pip install roomrubikspack
+```
+
+### Option 2: Install from GitHub
+```bash
+pip install git+https://github.com/yourusername/roomrubikspack.git
+```
+
+### Option 3: Local Installation (After Downloading)
+Navigate to the directory containing `pyproject.toml` and run:
+```bash
+pip install .
+```
+For local developers who want to modify the source code, run in editable mode:
+```bash
+pip install -e .
+```
+
+---
+
+## Configuring the Server Connection
+
+By default, the client library will look for your live API server running at `https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app`. 
+
+You can point to a different server endpoint in two ways:
+
+### 1. In Python Code (Recommended)
+Set the URL dynamically via `rr.settings()`:
+```python
+import roomrubikspack as rr
+
+rr.init()
+rr.settings(server_url="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app")
+```
+
+### 2. Via Environment Variable
+Before running your script, set the `ROOMRUBIKSPACK_SERVER_URL` environment variable:
+```bash
+# Windows PowerShell
+$env:ROOMRUBIKSPACK_SERVER_URL="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app"
+
+# Windows Command Prompt
+set ROOMRUBIKSPACK_SERVER_URL=https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app
+
+# Linux/macOS
+export ROOMRUBIKSPACK_SERVER_URL="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app"
+```
+
+---
+
+## Quick Start
+
+Here is a complete example. Make sure your local or remote RoomRubiks server is running before executing this script.
+
+```python
+import roomrubikspack as rr
+
+# Initialize session
+rr.init()
+
+# Configure the server (defaults to your live Cloud Run URL if omitted)
+rr.settings(unit="m", server_url="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app")
+
+# Define Rooms
+rr.room("living",   "Living Room",  area=20.0, startSpace=True)
+rr.room("kitchen",  "Kitchen",      w=3.0, h=3.0)
+rr.room("bed1",     "Master Bed",   area=16.0)
+rr.room("bath1",    "Attached Bath", area=4.0, attachedSpace=True)
+
+# Define site boundary
+rr.site([{"x": 0, "y": 0}, {"x": 20, "y": 0}, {"x": 20, "y": 20}, {"x": 0, "y": 20}])
+
+# Define connectivity
+rr.connectivity(
+    ("living", "kitchen"),
+    ("living", "bed1"),
+    ("bed1",   "bath1")
+)
+
+# Optional: Draw connectivity graph locally
+rr.connectivityshow()
+
+# Add constraints to guide layout generation
+rr.constraint("position", "bed1", "N")
+rr.constraint("area", None, 120)
+rr.constraint("perimeter", None, "minimize")
+
+# Generate sizes for rooms missing width/height
+rr.dimensiongen()
+
+# Generate layout variations (sent to the server engine)
+rr.generatelayout()
+
+# View first variation locally
+rr.showlayout(n=1, label=["name", "dim", "area"])
+
+# Export layout to DXF locally
+rr.exportlayout(n=1, filepath="output_layout.dxf")
+
+# Blocks execution until plots are closed
+rr.wait_for_plots()
+```
+
+---
+
+## API Reference
+
+- `rr.init()`: Clears all current session state.
+- `rr.settings(unit, server_url)`: Set global measurement units (`'m'` or `'f'`) and configure the solver backend API endpoint.
+- `rr.constructiongrid(add, remove, reset)`: View or manipulate the base construction grid sizes locally.
+- `rr.room(id, name, w, h, area, startSpace, attachedSpace, ...)`: Register a room.
+- `rr.site(points)`: Set an optional site boundary polygon.
+- `rr.connectivity(*pairs)`: Define room connections. Planarity check runs instantly on the client.
+- `rr.connectivityshow()`: Opens a Matplotlib window showing the adjacency graph.
+- `rr.constraint(type, room_id, value)`: Registers a layout constraint.
+- `rr.dimensiongen(avar, mar)`: Requests standard room dimensions from the server.
+- `rr.generatelayout(lvar, sgap, max_variations)`: Sends session state to the server to run the GA layout engine.
+- `rr.showlayout(n, label)`: Plots the `n`-th generated variation using Matplotlib.
+- `rr.exportlayout(n, filepath)`: Saves the `n`-th layout to JSON or DXF.
+- `rr.wait_for_plots()`: Helper to keep visual plots open.

roomrubikspack-0.1.0/README.md

@@ -0,0 +1,133 @@
+# RoomRubiksPack (Client Library)
+
+RoomRubiksPack is a lightweight Python package for generating architectural floorplan layouts using procedural generation and an Elitist Genetic Algorithm. 
+
+This client library maintains a local, stateful API for creating room models, local graphing/connectivity check, local plotting/visualisation via `matplotlib`, and local CAD exports via `ezdxf`. The computationally heavy layout generation (GA) and auto-dimensioning are offloaded to a RoomRubiks API Server.
+
+---
+
+## Installation
+
+### Option 1: Install from PyPI
+Once published, install the package via:
+```bash
+pip install roomrubikspack
+```
+
+### Option 2: Install from GitHub
+```bash
+pip install git+https://github.com/yourusername/roomrubikspack.git
+```
+
+### Option 3: Local Installation (After Downloading)
+Navigate to the directory containing `pyproject.toml` and run:
+```bash
+pip install .
+```
+For local developers who want to modify the source code, run in editable mode:
+```bash
+pip install -e .
+```
+
+---
+
+## Configuring the Server Connection
+
+By default, the client library will look for your live API server running at `https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app`. 
+
+You can point to a different server endpoint in two ways:
+
+### 1. In Python Code (Recommended)
+Set the URL dynamically via `rr.settings()`:
+```python
+import roomrubikspack as rr
+
+rr.init()
+rr.settings(server_url="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app")
+```
+
+### 2. Via Environment Variable
+Before running your script, set the `ROOMRUBIKSPACK_SERVER_URL` environment variable:
+```bash
+# Windows PowerShell
+$env:ROOMRUBIKSPACK_SERVER_URL="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app"
+
+# Windows Command Prompt
+set ROOMRUBIKSPACK_SERVER_URL=https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app
+
+# Linux/macOS
+export ROOMRUBIKSPACK_SERVER_URL="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app"
+```
+
+---
+
+## Quick Start
+
+Here is a complete example. Make sure your local or remote RoomRubiks server is running before executing this script.
+
+```python
+import roomrubikspack as rr
+
+# Initialize session
+rr.init()
+
+# Configure the server (defaults to your live Cloud Run URL if omitted)
+rr.settings(unit="m", server_url="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app")
+
+# Define Rooms
+rr.room("living",   "Living Room",  area=20.0, startSpace=True)
+rr.room("kitchen",  "Kitchen",      w=3.0, h=3.0)
+rr.room("bed1",     "Master Bed",   area=16.0)
+rr.room("bath1",    "Attached Bath", area=4.0, attachedSpace=True)
+
+# Define site boundary
+rr.site([{"x": 0, "y": 0}, {"x": 20, "y": 0}, {"x": 20, "y": 20}, {"x": 0, "y": 20}])
+
+# Define connectivity
+rr.connectivity(
+    ("living", "kitchen"),
+    ("living", "bed1"),
+    ("bed1",   "bath1")
+)
+
+# Optional: Draw connectivity graph locally
+rr.connectivityshow()
+
+# Add constraints to guide layout generation
+rr.constraint("position", "bed1", "N")
+rr.constraint("area", None, 120)
+rr.constraint("perimeter", None, "minimize")
+
+# Generate sizes for rooms missing width/height
+rr.dimensiongen()
+
+# Generate layout variations (sent to the server engine)
+rr.generatelayout()
+
+# View first variation locally
+rr.showlayout(n=1, label=["name", "dim", "area"])
+
+# Export layout to DXF locally
+rr.exportlayout(n=1, filepath="output_layout.dxf")
+
+# Blocks execution until plots are closed
+rr.wait_for_plots()
+```
+
+---
+
+## API Reference
+
+- `rr.init()`: Clears all current session state.
+- `rr.settings(unit, server_url)`: Set global measurement units (`'m'` or `'f'`) and configure the solver backend API endpoint.
+- `rr.constructiongrid(add, remove, reset)`: View or manipulate the base construction grid sizes locally.
+- `rr.room(id, name, w, h, area, startSpace, attachedSpace, ...)`: Register a room.
+- `rr.site(points)`: Set an optional site boundary polygon.
+- `rr.connectivity(*pairs)`: Define room connections. Planarity check runs instantly on the client.
+- `rr.connectivityshow()`: Opens a Matplotlib window showing the adjacency graph.
+- `rr.constraint(type, room_id, value)`: Registers a layout constraint.
+- `rr.dimensiongen(avar, mar)`: Requests standard room dimensions from the server.
+- `rr.generatelayout(lvar, sgap, max_variations)`: Sends session state to the server to run the GA layout engine.
+- `rr.showlayout(n, label)`: Plots the `n`-th generated variation using Matplotlib.
+- `rr.exportlayout(n, filepath)`: Saves the `n`-th layout to JSON or DXF.
+- `rr.wait_for_plots()`: Helper to keep visual plots open.

roomrubikspack-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "roomrubikspack"
+version = "0.1.0"
+authors = [
+    { name = "Vijesh Kumar V", email = "your.email@example.com" }
+]
+description = "Client wrapper for procedural architectural floorplan layout generator"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["architecture", "floorplan", "layout", "genetic-algorithm", "CAD", "procedural"]
+dependencies = [
+    "requests>=2.25.0",    # Server REST API communication
+    "matplotlib>=3.5.0",   # showlayout() and connectivityshow() visualisation
+    "networkx>=2.6.0",     # connectivityshow() network graph drawing
+    "ezdxf>=1.0.0"         # exportlayout() DXF export
+]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/roomrubikspack"
+"Bug Tracker" = "https://github.com/yourusername/roomrubikspack/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",         # Test runner
+    "pytest-cov>=4.0",     # Coverage reporting
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]            # src layout: package root is src/
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

roomrubikspack-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

roomrubikspack-0.1.0/src/roomrubikspack/__init__.py

@@ -0,0 +1,379 @@
+from typing import List, Dict, Tuple, Optional, Any
+import json
+import dataclasses
+import requests
+import os
+
+from .types import Room, Connection, Site, Door, Window, Furniture
+from .utils.graph_utils import check_planarity
+from .utils.constraints import add_constraint, clear_constraints
+
+# Session state kept on the client side
+_rooms: List[Room] = []
+_connections: List[Connection] = []
+_site: Optional[Site] = None
+_layout_variations: List[List[Room]] = []
+_DEFAULT_GRID_SIZES: List[float] = [1.2, 1.5, 1.8, 2.1, 2.4, 3.0, 4.5, 6.0, 7.5, 9.0]
+_base_grid_sizes: List[float] = _DEFAULT_GRID_SIZES.copy()
+_settings: Dict[str, str] = {"unit": "m"}
+
+# Configurable server URL (falls back to live Cloud Run or environment variable)
+_server_url: str = os.getenv("ROOMRUBIKSPACK_SERVER_URL", "https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app").rstrip('/')
+
+
+def deserialize_door(d: Dict[str, Any]) -> Door:
+    valid_fields = {f.name for f in dataclasses.fields(Door)}
+    filtered_data = {k: v for k, v in d.items() if k in valid_fields}
+    return Door(**filtered_data)
+
+
+def deserialize_window(w: Dict[str, Any]) -> Window:
+    valid_fields = {f.name for f in dataclasses.fields(Window)}
+    filtered_data = {k: v for k, v in w.items() if k in valid_fields}
+    return Window(**filtered_data)
+
+
+def deserialize_furniture(f: Dict[str, Any]) -> Furniture:
+    valid_fields = {f.name for f in dataclasses.fields(Furniture)}
+    filtered_data = {k: v for k, v in f.items() if k in valid_fields}
+    return Furniture(**filtered_data)
+
+
+def deserialize_room(r: Dict[str, Any]) -> Room:
+    # Separate nested complex structures
+    doors_data = r.pop("doors", []) or []
+    windows_data = r.pop("windows", []) or []
+    furniture_data = r.pop("furniture", []) or []
+    
+    doors = [deserialize_door(d) for d in doors_data if isinstance(d, dict)]
+    windows = [deserialize_window(w) for w in windows_data if isinstance(w, dict)]
+    furniture = [deserialize_furniture(f) for f in furniture_data if isinstance(f, dict)]
+    
+    # Filter flat dictionary to match dataclass fields
+    valid_fields = {f.name for f in dataclasses.fields(Room)}
+    filtered_data = {k: v for k, v in r.items() if k in valid_fields}
+    
+    room_obj = Room(**filtered_data)
+    room_obj.doors = doors
+    room_obj.windows = windows
+    room_obj.furniture = furniture
+    return room_obj
+
+
+def init():
+    """Initializes a new session/project (clears any existing state)."""
+    global _rooms, _connections, _site, _layout_variations, _base_grid_sizes
+    _rooms = []
+    _connections = []
+    _site = None
+    _layout_variations = []
+    _base_grid_sizes = _DEFAULT_GRID_SIZES.copy()
+    clear_constraints()
+    print("RoomRubiks session initialized successfully.")
+
+
+def room(id: str, name: str = "", **kwargs):
+    """Adds a room to the session and prints a success message with details."""
+    global _rooms
+    new_room = Room(id=id, name=name, **kwargs)
+    _rooms.append(new_room)
+    details = f"Area: {new_room.area} " if new_room.area else f"Size: {new_room.w}x{new_room.h} "
+    start_space_msg = " (Start Space)" if new_room.startSpace else ""
+    print(f"Added room successfully: {new_room.name} ({new_room.id}) - {details}{start_space_msg}")
+    return new_room
+
+
+def connectivity(*conn_pairs: Tuple[str, str]):
+    """Registers the connections, runs a planarity check, prints a message."""
+    global _connections, _rooms
+    
+    for pair in conn_pairs:
+        _connections.append(Connection(roomA=pair[0], roomB=pair[1]))
+        
+    start_spaces = [r for r in _rooms if r.startSpace]
+    
+    print(f"Added {len(conn_pairs)} connections.")
+    
+    if len(start_spaces) != 1:
+        print(f"WARNING: There must be exactly one start space. Found {len(start_spaces)}.")
+    else:
+        print(f"Start space verified: {start_spaces[0].name}")
+        
+    room_ids = [r.id for r in _rooms]
+    is_planar = check_planarity(room_ids, _connections)
+    if is_planar:
+        print("Planarity check passed: The connectivity graph satisfies Euler's formula.")
+    else:
+        print("WARNING: The provided connectivity graph is non-planar.")
+
+
+def connectivityshow():
+    """Shows a matplotlib network diagram of the registered connectivity."""
+    global _connections, _rooms
+    if not _rooms or not _connections:
+        print("No rooms or connections registered to show.")
+        return
+
+    try:
+        import matplotlib.pyplot as plt
+        import networkx as nx
+    except ImportError:
+        print("Please install matplotlib and networkx to use connectivityshow(): pip install matplotlib networkx")
+        return
+
+    G = nx.Graph()
+    
+    for r in _rooms:
+        G.add_node(r.id, label=r.name or r.id, is_start=getattr(r, 'startSpace', False))
+        
+    for c in _connections:
+        G.add_edge(c.roomA, c.roomB)
+
+    pos = nx.spring_layout(G, seed=42)
+    labels = nx.get_node_attributes(G, 'label')
+    colors = ['lightgreen' if nx.get_node_attributes(G, 'is_start').get(n) else 'lightblue' for n in G.nodes()]
+
+    plt.figure(figsize=(8, 6))
+    nx.draw(G, pos, labels=labels, node_color=colors, with_labels=True, node_size=2000, font_size=10, font_weight="bold", edge_color="gray")
+    plt.title("Connectivity Network Diagram")
+    plt.show(block=False)
+
+
+def site(points: List[Dict[str, float]]):
+    """Defines the optional site boundary."""
+    global _site
+    _site = Site(points=points)
+    print("Site boundary added successfully.")
+
+
+def constraint(constraint_type: str, room_id: Optional[str] = None, value: Any = None):
+    """Adds a constraint (e.g. position, area, perimeter) for the layout generator."""
+    add_constraint(constraint_type, room_id, value)
+    print(f"Added constraint: {constraint_type} for room {room_id} with value {value}")
+
+
+def settings(unit: Optional[str] = None, server_url: Optional[str] = None):
+    """Sets global project settings and server endpoint."""
+    global _settings, _server_url
+    if unit is not None:
+        unit = unit.lower()
+        if unit not in ['m', 'f']:
+            print("Warning: Unsupported unit. Use 'm' for meters or 'f' for feet.")
+        else:
+            _settings["unit"] = unit
+            print(f"Settings updated: unit set to '{unit}'")
+            
+    if server_url is not None:
+        _server_url = server_url.rstrip('/')
+        print(f"Settings updated: server URL set to '{_server_url}'")
+
+
+def constructiongrid(add: Optional[float] = None, remove: Optional[float] = None, reset: bool = False):
+    """Shows or modifies the base construction grid sizes used by dimensiongen."""
+    global _base_grid_sizes, _DEFAULT_GRID_SIZES
+    
+    if reset:
+        _base_grid_sizes = _DEFAULT_GRID_SIZES.copy()
+        print("Construction grid reset to defaults.")
+        return _base_grid_sizes
+        
+    if add is not None:
+        if add not in _base_grid_sizes:
+            _base_grid_sizes.append(float(add))
+            _base_grid_sizes.sort()
+            print(f"Added {add} to construction grid.")
+        else:
+            print(f"{add} is already in the construction grid.")
+    if remove is not None:
+        if remove in _base_grid_sizes:
+            _base_grid_sizes.remove(float(remove))
+            print(f"Removed {remove} from construction grid.")
+        else:
+            print(f"{remove} is not in the construction grid.")
+            
+    print(f"Current base construction grid: {_base_grid_sizes}")
+    return _base_grid_sizes
+
+
+def dimensiongen(avar: float = 0.10, mar: float = 1.5):
+    """Calculates optimal dimensions for rooms missing them using the server."""
+    global _rooms, _base_grid_sizes, _server_url
+    
+    payload = {
+        "rooms": [dataclasses.asdict(r) for r in _rooms],
+        "base_grid_sizes": _base_grid_sizes,
+        "area_variation": avar,
+        "max_aspect_ratio": mar
+    }
+    
+    print(f"Requesting dimensions from server at {_server_url}...")
+    try:
+        response = requests.post(f"{_server_url}/dimensiongen", json=payload, timeout=30)
+        response.raise_for_status()
+        data = response.json()
+    except Exception as e:
+        print(f"Error connecting to RoomRubiks server: {e}")
+        print("Please check if the server is running and configured correctly.")
+        return {}
+        
+    # Reconstruct rooms and update _rooms
+    updated_rooms = []
+    for rm_dict in data["rooms"]:
+        updated_rooms.append(deserialize_room(rm_dict))
+    _rooms = updated_rooms
+    
+    saved_dimensions = data["saved_dimensions"]
+    print(f"Generated dimensions for {len(saved_dimensions)} rooms.")
+    print(f"Dimensions details: {saved_dimensions}")
+    return saved_dimensions
+
+
+def generatelayout(lvar: float = 0.5, sgap: float = 1.0, max_variations: int = 10, liked_layouts: Optional[List[Any]] = None):
+    """Generates the architectural layouts using the server-side Elitist Genetic Algorithm."""
+    global _rooms, _connections, _site, _settings, _layout_variations, _server_url
+    print(f"Generating layout on server ({_server_url}) with location_variation={lvar}, allowed_space_gap={sgap}...")
+    
+    from .utils.constraints import _global_constraints
+    
+    payload = {
+        "rooms": [dataclasses.asdict(r) for r in _rooms],
+        "connections": [dataclasses.asdict(c) for c in _connections],
+        "constraints": _global_constraints,
+        "site": dataclasses.asdict(_site) if _site is not None else None,
+        "settings": _settings,
+        "location_variation": lvar,
+        "allowed_space_gap": sgap,
+        "max_variations": max_variations
+    }
+    
+    try:
+        response = requests.post(f"{_server_url}/generatelayout", json=payload, timeout=60)
+        response.raise_for_status()
+        data = response.json()
+    except Exception as e:
+        print(f"Error connecting to RoomRubiks server: {e}")
+        print("Please check if the server is running and configured correctly.")
+        return []
+        
+    variations = []
+    for var_dict in data["variations"]:
+        var_rooms = [deserialize_room(rm_dict) for rm_dict in var_dict]
+        variations.append(var_rooms)
+        
+    _layout_variations = variations
+    if not variations:
+        print("Failed to generate layouts.")
+    else:
+        print(f"Successfully generated {len(variations)} unique variations.")
+    return variations
+
+
+def showlayout(n: int = 1, label: Optional[List[str]] = None):
+    """Shows a matplotlib plot of the n-th layout variation."""
+    global _layout_variations
+    if not _layout_variations or n < 1 or n > len(_layout_variations):
+        print(f"Variation {n} does not exist. Available variations: {len(_layout_variations)}")
+        return
+        
+    layout = _layout_variations[n - 1]
+    
+    try:
+        import matplotlib.pyplot as plt
+        import matplotlib.patches as patches
+    except ImportError:
+        print("Please install matplotlib to use showlayout(): pip install matplotlib")
+        return
+
+    fig, ax = plt.subplots()
+    
+    global _site
+    if _site is not None and getattr(_site, 'points', None):
+        site_pts = [(pt['x'], pt['y']) for pt in _site.points]
+        poly = patches.Polygon(site_pts, closed=True, fill=False, edgecolor='red', linestyle='--', linewidth=2)
+        ax.add_patch(poly)
+        
+    if label is None:
+        label = ["name"]
+        
+    for r in layout:
+        is_corr = getattr(r, 'isCorridor', False)
+        color = '#e2e8f0' if is_corr else getattr(r, 'color', '#ffffff')
+        rect = patches.Rectangle((r.x, r.y), r.w, r.h, linewidth=1, edgecolor='black', facecolor=color, alpha=0.8)
+        ax.add_patch(rect)
+        if not is_corr:
+            label_parts = []
+            unit_str = "m" if _settings["unit"] == "m" else "ft"
+            sq_unit_str = "sq.m" if _settings["unit"] == "m" else "sq.ft"
+            
+            if "name" in label:
+                label_parts.append(r.name or r.id)
+            if "id" in label:
+                label_parts.append(r.id)
+            if "dim" in label:
+                label_parts.append(f"{r.w}x{r.h}{unit_str}")
+            if "area" in label:
+                calc_area = round(r.w * r.h, 1)
+                label_parts.append(f"{calc_area} {sq_unit_str}")
+            
+            text_str = "\n".join(label_parts)
+            ax.text(r.x + r.w/2, r.y + r.h/2, text_str, ha='center', va='center', fontsize=8)
+
+    ax.autoscale()
+    plt.gca().set_aspect('equal', adjustable='box')
+    plt.title(f"Layout Variation {n}")
+    plt.show(block=False)
+
+
+def exportlayout(n: int = 1, filepath: str = "layout.json"):
+    """Exports the n-th layout variation to JSON or DXF."""
+    global _layout_variations
+    if not _layout_variations or n < 1 or n > len(_layout_variations):
+        print(f"Variation {n} does not exist.")
+        return
+        
+    layout = _layout_variations[n - 1]
+    
+    if filepath.lower().endswith(".json"):
+        data = []
+        for r in layout:
+            data.append({
+                "id": r.id,
+                "name": getattr(r, 'name', ''),
+                "isCorridor": getattr(r, 'isCorridor', False),
+                "x": r.x,
+                "y": r.y,
+                "w": r.w,
+                "h": r.h
+            })
+        with open(filepath, 'w') as f:
+            json.dump(data, f, indent=2)
+        print(f"Exported variation {n} to {os.path.abspath(filepath)}")
+    elif filepath.lower().endswith(".dxf"):
+        try:
+            import ezdxf
+        except ImportError:
+            print("DXF export skipped (ezdxf not installed).")
+            return
+            
+        doc = ezdxf.new('R2010')
+        msp = doc.modelspace()
+        
+        for r in layout:
+            pts = [(r.x, r.y), (r.x + r.w, r.y), (r.x + r.w, r.y + r.h), (r.x, r.y + r.h)]
+            msp.add_lwpolyline(pts, close=True)
+            if not getattr(r, 'isCorridor', False):
+                msp.add_text(r.name or r.id, dxfattribs={'height': 0.2}).set_placement((r.x + r.w/2, r.y + r.h/2))
+                
+        doc.saveas(filepath)
+        print(f"Exported variation {n} to {os.path.abspath(filepath)}")
+    else:
+        print("Unsupported file format. Please use .json or .dxf")
+
+
+def wait_for_plots():
+    """Blocks execution until all matplotlib windows are closed by the user."""
+    try:
+        import matplotlib.pyplot as plt
+        plt.show(block=True)
+    except ImportError:
+        pass

roomrubikspack-0.1.0/src/roomrubikspack/types.py

@@ -0,0 +1,138 @@
+"""
+types.py
+
+Defines all shared dataclasses (data models) used throughout the package.
+These act as plain data containers — no methods or business logic lives here.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+
+
+@dataclass
+class Window:
+    """Represents a window element placed inside a room."""
+    id: str                         # Unique window identifier
+    worldX: float                   # X position in world coordinates (metres)
+    worldY: float                   # Y position in world coordinates (metres)
+    widthM: float                   # Width of the window opening (metres)
+    lengthM: float                  # Depth/thickness of the window (metres)
+    isVertical: bool                # True = window sits on a vertical (N/S) wall
+    sillHeight: Optional[float] = None  # Height of the window sill from floor level
+
+
+@dataclass
+class Door:
+    """Represents a door element placed inside a room."""
+    id: str                         # Unique door identifier
+    worldX: float                   # X position in world coordinates (metres)
+    worldY: float                   # Y position in world coordinates (metres)
+    widthM: float                   # Clear opening width (metres)
+    lengthM: float                  # Door panel depth (metres)
+    isVertical: bool                # True = door sits on a vertical (N/S) wall
+    isMain: Optional[bool] = False          # True = main entrance door
+    isOpening: Optional[bool] = False       # True = opening only (no panel drawn)
+    hingeX: Optional[float] = None          # X coordinate of the hinge pivot
+    hingeY: Optional[float] = None          # Y coordinate of the hinge pivot
+    swingDirX: Optional[float] = None       # X component of the swing direction vector
+    swingDirY: Optional[float] = None       # Y component of the swing direction vector
+    _candidates: Optional[List[Any]] = None # Internal: candidate placement positions
+    _candidateIdx: Optional[int] = None     # Internal: chosen candidate index
+    doorCount: Optional[int] = None         # Number of doors in a multi-leaf set
+
+
+@dataclass
+class Furniture:
+    """Represents a furniture item placed inside a room."""
+    id: str                             # Unique furniture identifier
+    type: str                           # Category string e.g. "bed", "desk", "sofa"
+    worldX: float                       # X position in world coordinates (metres)
+    worldY: float                       # Y position in world coordinates (metres)
+    widthM: float                       # Width of the furniture piece (metres)
+    lengthM: float                      # Length of the furniture piece (metres)
+    rotation: float                     # Rotation angle in degrees (0 = facing right)
+    color: Optional[str] = None         # Hex fill colour for rendering
+    mirrored: Optional[bool] = False    # True = horizontally flipped
+    isResponsiveSet: Optional[bool] = False  # True = part of a responsive furniture set
+
+
+@dataclass
+class Room:
+    """
+    Core room model.
+    A room can either have explicit dimensions (w, h) or just an area —
+    dimensiongen() will resolve the latter into w/h automatically.
+    """
+    id: str                                     # Unique room identifier (user-defined)
+    name: str = ""                              # Human-readable room label
+    x: float = 0.0                             # Initial X position hint (metres); refined by GA
+    y: float = 0.0                             # Initial Y position hint (metres); refined by GA
+    w: Optional[float] = None                  # Width (metres); set by user or dimensiongen()
+    h: Optional[float] = None                  # Height (metres); set by user or dimensiongen()
+    area: Optional[float] = None               # Target floor area in m²; triggers auto-dimensioning
+    color: str = "#ffffff"                      # Display fill colour
+    attached: bool = False                      # True = placed inside/onto a parent room
+    startSpace: bool = False                    # True = entry point; exactly one room must be True
+    attachedSpace: bool = False                 # True = user-declared dependent room (e.g. en-suite)
+    isCorridor: Optional[bool] = False          # True = corridor strip (auto-created by layout engine)
+    wallPresent: Optional[bool] = True          # False = room boundary is open (no wall drawn)
+    doors: Optional[List[Door]] = field(default_factory=list)       # Doors on this room's walls
+    windows: Optional[List[Window]] = field(default_factory=list)   # Windows on this room's walls
+    furniture: Optional[List[Furniture]] = field(default_factory=list)  # Furniture inside the room
+    labelOffsetX: Optional[float] = None        # Fine-tune label X offset for rendering
+    labelOffsetY: Optional[float] = None        # Fine-tune label Y offset for rendering
+    levelId: Optional[str] = None              # Floor/level this room belongs to
+    layerId: Optional[str] = None              # Drawing layer identifier
+    nameFontSize: Optional[float] = None        # Override name label font size
+    dimFontSize: Optional[float] = None         # Override dimension label font size
+    areaFontSize: Optional[float] = None        # Override area label font size
+    wfr: Optional[float] = None                # Window-to-floor ratio (used in daylighting calc)
+    activityDbA: Optional[float] = None         # Acoustic activity level in dBA
+    lightingTargetLux: Optional[float] = None   # Daylighting target illuminance (lux)
+    lightingTargetHours: Optional[float] = None # Required daylighting hours per day
+    unconnectedHeight: Optional[float] = None   # Ceiling height if disconnected from standard storey
+    topLevelId: Optional[str] = None           # Top-most level if the room spans multiple levels
+    windowRegenCount: Optional[int] = None      # Number of times windows have been regenerated
+
+
+@dataclass
+class Connection:
+    """
+    Represents an adjacency requirement between two rooms.
+    The layout engine tries to place roomA and roomB with a shared wall.
+    """
+    roomA: str                  # ID of the first room
+    roomB: str                  # ID of the second room
+    id: Optional[str] = None    # Auto-generated as "roomA_roomB" if not provided
+
+    def __post_init__(self):
+        # Auto-generate a stable connection ID if the user didn't supply one
+        if self.id is None:
+            self.id = f"{self.roomA}_{self.roomB}"
+
+
+@dataclass
+class Site:
+    """
+    Optional outer site boundary polygon.
+    If defined, the layout engine can attempt to fit the rooms within it.
+    """
+    points: List[Dict[str, float]]  # List of {x, y} dicts defining the polygon vertices
+    width: Optional[float] = None   # Bounding width of the site (derived or explicit)
+    height: Optional[float] = None  # Bounding height of the site (derived or explicit)
+    layerId: Optional[str] = None   # Drawing layer for the site polygon
+    offsets: Optional[List[float]] = None  # Setback distances [top, right, bottom, left]
+
+
+@dataclass
+class Road:
+    """
+    Represents a road or access path adjacent to the site.
+    Used for orientation and entry point determination.
+    """
+    id: str                             # Unique road identifier
+    points: List[Dict[str, float]]      # Centreline polyline as list of {x, y}
+    width: float                        # Road width in metres
+    direction: Optional[str] = None     # Cardinal direction of the road (N, S, E, W)
+    layerId: Optional[str] = None       # Drawing layer identifier
+    isInternal: Optional[bool] = False  # True = internal driveway or pedestrian path

roomrubikspack-0.1.0/src/roomrubikspack/utils/__init__.py

@@ -0,0 +1 @@
+# roomrubikspack utils

roomrubikspack-0.1.0/src/roomrubikspack/utils/constraints.py

@@ -0,0 +1,19 @@
+from typing import List, Dict, Any, Optional
+
+_global_constraints: List[Dict[str, Any]] = []
+
+def add_constraint(constraint_type: str, room_id: Optional[str] = None, value: Any = None):
+    """
+    Appends a new constraint to the global constraint list.
+    Called internally by rr.constraint().
+    """
+    _global_constraints.append({
+        "type": constraint_type,   # One of: "position", "area", "perimeter"
+        "room_id": room_id,        # Target room for positional constraints; None for global ones
+        "value": value             # Meaning depends on type
+    })
+
+def clear_constraints():
+    """Resets the global constraint list. Called by rr.init() at session start."""
+    global _global_constraints
+    _global_constraints = []

roomrubikspack-0.1.0/src/roomrubikspack/utils/graph_utils.py

@@ -0,0 +1,143 @@
+"""
+utils/graph_utils.py
+
+Graph utilities for the roomrubikspack layout engine.
+
+Responsibilities:
+- check_connectivity : verify all rooms form a single connected graph
+- get_bfs_order      : produce a Breadth-First Search traversal order for placement
+- check_planarity    : quick Euler formula check to warn about non-planar graphs
+"""
+
+import random
+from typing import List, Dict, Optional, Set
+from ..types import Connection
+
+
+def check_connectivity(room_ids: List[str], connections: List[Connection]) -> bool:
+    """
+    Returns True if all rooms are reachable from the first room (i.e. the graph is connected).
+    A disconnected graph would mean some rooms can never be placed adjacent to the start.
+    """
+    if len(room_ids) <= 1:
+        return True  # A single room or empty list is trivially connected
+
+    # Build adjacency list from the connection list
+    adj: Dict[str, List[str]] = {r_id: [] for r_id in room_ids}
+    for conn in connections:
+        if conn.roomA in adj:
+            adj[conn.roomA].append(conn.roomB)
+        if conn.roomB in adj:
+            adj[conn.roomB].append(conn.roomA)
+
+    # Standard BFS from the first room
+    visited: Set[str] = set()
+    queue = [room_ids[0]]
+    visited.add(room_ids[0])
+
+    while queue:
+        u = queue.pop(0)
+        for v in adj.get(u, []):
+            if v not in visited:
+                visited.add(v)
+                queue.append(v)
+
+    # All rooms must be visited for the graph to be connected
+    return len(visited) == len(room_ids)
+
+
+def get_bfs_order(
+    room_ids: List[str],
+    connections: List[Connection],
+    start_room_id: Optional[str] = None,
+    shuffle_list: bool = False
+) -> List[str]:
+    """
+    Returns the room IDs in Breadth-First Search order starting from start_room_id.
+    This order is used by the layout generator to place rooms one-by-one, ensuring
+    that each room's parent is already placed before the room itself is processed.
+
+    Args:
+        room_ids       : all room IDs to traverse
+        connections    : adjacency edges between rooms
+        start_room_id  : the room to begin traversal from (should be startSpace)
+        shuffle_list   : if True, randomises neighbour order at each BFS step
+                         (used by the GA to explore different layout topologies)
+    """
+    if not room_ids:
+        return []
+
+    # Build undirected adjacency list restricted to provided room_ids
+    adj: Dict[str, List[str]] = {r_id: [] for r_id in room_ids}
+    for conn in connections:
+        if conn.roomA in adj:
+            adj[conn.roomA].append(conn.roomB)
+        if conn.roomB in adj:
+            adj[conn.roomB].append(conn.roomA)
+
+    order: List[str] = []
+    visited: Set[str] = set()
+
+    # Fall back to first room if start_room_id is not found
+    start_id = start_room_id if (start_room_id and start_room_id in room_ids) else room_ids[0]
+
+    queue = [start_id]
+    visited.add(start_id)
+
+    while queue:
+        u = queue.pop(0)
+        order.append(u)
+
+        neighbors = list(adj.get(u, []))
+        if shuffle_list:
+            random.shuffle(neighbors)   # Random order = different layout exploration
+        else:
+            neighbors.sort()            # Deterministic order for reproducibility
+
+        for v in neighbors:
+            if v not in visited:
+                visited.add(v)
+                queue.append(v)
+
+    # Handle disconnected components — append them after the main connected component
+    for r_id in room_ids:
+        if r_id not in visited:
+            sub_queue = [r_id]
+            visited.add(r_id)
+            while sub_queue:
+                u = sub_queue.pop(0)
+                order.append(u)
+                neighbors = list(adj.get(u, []))
+                if shuffle_list:
+                    random.shuffle(neighbors)
+                else:
+                    neighbors.sort()
+                for v in neighbors:
+                    if v not in visited:
+                        visited.add(v)
+                        sub_queue.append(v)
+
+    return order
+
+
+def check_planarity(room_ids: List[str], connections: List[Connection]) -> bool:
+    """
+    Quick necessary-condition check for graph planarity using Euler's formula.
+    For a planar graph: E ≤ 3V − 6  (where V = vertices, E = edges).
+
+    NOTE: This is a necessary but NOT sufficient condition. It will catch
+    obvious non-planar cases but not all of them. Use as a warning only.
+
+    Returns True if the graph MIGHT be planar, False if it is DEFINITELY non-planar.
+    """
+    v = len(room_ids)   # Number of vertices (rooms)
+    e = len(connections)  # Number of edges (connections)
+
+    if v <= 2:
+        return True  # Any graph with ≤2 vertices is always planar
+
+    # Euler's inequality: a planar graph cannot have more than 3V-6 edges
+    if e > 3 * v - 6:
+        return False  # Definitely non-planar
+
+    return True  # Likely planar (not guaranteed)

roomrubikspack-0.1.0/src/roomrubikspack.egg-info/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: roomrubikspack
+Version: 0.1.0
+Summary: Client wrapper for procedural architectural floorplan layout generator
+Author-email: Vijesh Kumar V <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/roomrubikspack
+Project-URL: Bug Tracker, https://github.com/yourusername/roomrubikspack/issues
+Keywords: architecture,floorplan,layout,genetic-algorithm,CAD,procedural
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: networkx>=2.6.0
+Requires-Dist: ezdxf>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# RoomRubiksPack (Client Library)
+
+RoomRubiksPack is a lightweight Python package for generating architectural floorplan layouts using procedural generation and an Elitist Genetic Algorithm. 
+
+This client library maintains a local, stateful API for creating room models, local graphing/connectivity check, local plotting/visualisation via `matplotlib`, and local CAD exports via `ezdxf`. The computationally heavy layout generation (GA) and auto-dimensioning are offloaded to a RoomRubiks API Server.
+
+---
+
+## Installation
+
+### Option 1: Install from PyPI
+Once published, install the package via:
+```bash
+pip install roomrubikspack
+```
+
+### Option 2: Install from GitHub
+```bash
+pip install git+https://github.com/yourusername/roomrubikspack.git
+```
+
+### Option 3: Local Installation (After Downloading)
+Navigate to the directory containing `pyproject.toml` and run:
+```bash
+pip install .
+```
+For local developers who want to modify the source code, run in editable mode:
+```bash
+pip install -e .
+```
+
+---
+
+## Configuring the Server Connection
+
+By default, the client library will look for your live API server running at `https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app`. 
+
+You can point to a different server endpoint in two ways:
+
+### 1. In Python Code (Recommended)
+Set the URL dynamically via `rr.settings()`:
+```python
+import roomrubikspack as rr
+
+rr.init()
+rr.settings(server_url="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app")
+```
+
+### 2. Via Environment Variable
+Before running your script, set the `ROOMRUBIKSPACK_SERVER_URL` environment variable:
+```bash
+# Windows PowerShell
+$env:ROOMRUBIKSPACK_SERVER_URL="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app"
+
+# Windows Command Prompt
+set ROOMRUBIKSPACK_SERVER_URL=https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app
+
+# Linux/macOS
+export ROOMRUBIKSPACK_SERVER_URL="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app"
+```
+
+---
+
+## Quick Start
+
+Here is a complete example. Make sure your local or remote RoomRubiks server is running before executing this script.
+
+```python
+import roomrubikspack as rr
+
+# Initialize session
+rr.init()
+
+# Configure the server (defaults to your live Cloud Run URL if omitted)
+rr.settings(unit="m", server_url="https://roomrubikspack-0-1-0-private-942524616275.asia-south1.run.app")
+
+# Define Rooms
+rr.room("living",   "Living Room",  area=20.0, startSpace=True)
+rr.room("kitchen",  "Kitchen",      w=3.0, h=3.0)
+rr.room("bed1",     "Master Bed",   area=16.0)
+rr.room("bath1",    "Attached Bath", area=4.0, attachedSpace=True)
+
+# Define site boundary
+rr.site([{"x": 0, "y": 0}, {"x": 20, "y": 0}, {"x": 20, "y": 20}, {"x": 0, "y": 20}])
+
+# Define connectivity
+rr.connectivity(
+    ("living", "kitchen"),
+    ("living", "bed1"),
+    ("bed1",   "bath1")
+)
+
+# Optional: Draw connectivity graph locally
+rr.connectivityshow()
+
+# Add constraints to guide layout generation
+rr.constraint("position", "bed1", "N")
+rr.constraint("area", None, 120)
+rr.constraint("perimeter", None, "minimize")
+
+# Generate sizes for rooms missing width/height
+rr.dimensiongen()
+
+# Generate layout variations (sent to the server engine)
+rr.generatelayout()
+
+# View first variation locally
+rr.showlayout(n=1, label=["name", "dim", "area"])
+
+# Export layout to DXF locally
+rr.exportlayout(n=1, filepath="output_layout.dxf")
+
+# Blocks execution until plots are closed
+rr.wait_for_plots()
+```
+
+---
+
+## API Reference
+
+- `rr.init()`: Clears all current session state.
+- `rr.settings(unit, server_url)`: Set global measurement units (`'m'` or `'f'`) and configure the solver backend API endpoint.
+- `rr.constructiongrid(add, remove, reset)`: View or manipulate the base construction grid sizes locally.
+- `rr.room(id, name, w, h, area, startSpace, attachedSpace, ...)`: Register a room.
+- `rr.site(points)`: Set an optional site boundary polygon.
+- `rr.connectivity(*pairs)`: Define room connections. Planarity check runs instantly on the client.
+- `rr.connectivityshow()`: Opens a Matplotlib window showing the adjacency graph.
+- `rr.constraint(type, room_id, value)`: Registers a layout constraint.
+- `rr.dimensiongen(avar, mar)`: Requests standard room dimensions from the server.
+- `rr.generatelayout(lvar, sgap, max_variations)`: Sends session state to the server to run the GA layout engine.
+- `rr.showlayout(n, label)`: Plots the `n`-th generated variation using Matplotlib.
+- `rr.exportlayout(n, filepath)`: Saves the `n`-th layout to JSON or DXF.
+- `rr.wait_for_plots()`: Helper to keep visual plots open.

roomrubikspack-0.1.0/src/roomrubikspack.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/roomrubikspack/__init__.py
+src/roomrubikspack/types.py
+src/roomrubikspack.egg-info/PKG-INFO
+src/roomrubikspack.egg-info/SOURCES.txt
+src/roomrubikspack.egg-info/dependency_links.txt
+src/roomrubikspack.egg-info/requires.txt
+src/roomrubikspack.egg-info/top_level.txt
+src/roomrubikspack/utils/__init__.py
+src/roomrubikspack/utils/constraints.py
+src/roomrubikspack/utils/graph_utils.py

roomrubikspack-0.1.0/src/roomrubikspack.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

roomrubikspack-0.1.0/src/roomrubikspack.egg-info/requires.txt

@@ -0,0 +1,8 @@
+requests>=2.25.0
+matplotlib>=3.5.0
+networkx>=2.6.0
+ezdxf>=1.0.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0

roomrubikspack-0.1.0/src/roomrubikspack.egg-info/top_level.txt

@@ -0,0 +1 @@
+roomrubikspack