diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 657ac95..3d6709a 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -86,6 +86,12 @@ classDiagram +Graph ReferenceGraph } + class PlanGenerationConstraints { + +Polygon BoundingPolygon + +Vector2? FrontDoorFacing + +Vector2? GarageFacing + } + class Graph { +Dictionary Nodes +List~Edge~ Edges @@ -121,6 +127,10 @@ classDiagram * `Geometries`: A dictionary mapping category names (e.g., "living", "wall", "door") to lists of NetTopologySuite `Geometry` objects. * `Bounds`: The spatial bounding box of the plan. * `ReferenceGraph`: The ground-truth graph provided by the dataset (if available). +* **`PlanGenerationConstraints`**: Configuration for filtering and orienting loaded plans. + * `BoundingPolygon`: A polygon that must fully contain the plan's bounds. + * `FrontDoorFacing`: A target vector for the front door's orientation relative to the plan's center. + * `GarageFacing`: *Unsupported in current dataset*. * **`Graph`**: Represents the connectivity graph of the floorplan. * Generated by `GraphGenerator` or loaded as `ReferenceGraph`. * **`Node`**: A node in the graph, typically representing a room or a portal (door/window). @@ -135,11 +145,15 @@ classDiagram Handles the loading of plan data. -* `static Task> LoadPlansAsync(string jsonPath = null, string pklPathOverride = null, int? maxItems = null, Action logger = null)` +* `static Task> LoadPlansAsync(string jsonPath = null, string pklPathOverride = null, int? maxItems = null, Action logger = null, PlanGenerationConstraints constraints = null)` * **jsonPath**: Optional path to a pre-converted JSON file. If provided, skips Python execution. * **pklPathOverride**: Optional path to a specific `.pkl` file. If null, defaults to the managed dataset path. * **maxItems**: Optional limit on the number of plans to load. * **logger**: Optional callback to receive real-time progress updates (e.g., dependency installation logs, download progress). + * **constraints**: Optional `PlanGenerationConstraints` to filter or orient plans. + * **BoundingPolygon**: If set, only plans whose bounds are completely contained within this polygon are returned. + * **FrontDoorFacing**: If set, plans are rotated so their front door (vector from center to door) aligns with this vector. + * **GarageFacing**: Currently unsupported; will log a warning if set. * **Returns**: A list of `Plan` objects. ### `ResPlan.Library.Data.PlanSerializer` diff --git a/README.md b/README.md index 349a905..1645acb 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,43 @@ var plans = await PlanLoader.LoadPlansAsync( Console.WriteLine($"Loaded {plans.Count} plans."); ``` -### 2. Generating Connectivity Graphs +### 2. Applying Constraints (Optional) + +You can filter and orient plans using `PlanGenerationConstraints`. + +```csharp +using NetTopologySuite.Geometries; +using System.Numerics; + +// Define a bounding box polygon (must contain the plan) +var coordinates = new[] +{ + new Coordinate(0, 0), + new Coordinate(100, 0), + new Coordinate(100, 100), + new Coordinate(0, 100), + new Coordinate(0, 0) // Close the loop +}; +var boundingPoly = new GeometryFactory().CreatePolygon(coordinates); + +// Define constraints +var constraints = new PlanGenerationConstraints +{ + // Filter: Plan must fit inside this polygon + BoundingPolygon = boundingPoly, + + // Orientation: Rotate plan so the front door faces "Up" (positive Y) + FrontDoorFacing = new Vector2(0, 1) +}; + +var constrainedPlans = await PlanLoader.LoadPlansAsync( + maxItems: 5, + logger: logger, + constraints: constraints +); +``` + +### 3. Generating Connectivity Graphs Once a `Plan` is loaded, you can generate a graph representing the connectivity between rooms, doors, and windows using `GraphGenerator`. @@ -67,7 +103,7 @@ foreach (var plan in plans) } ``` -### 3. Rendering Floorplans +### 4. Rendering Floorplans You can visualize the floorplan using `PlanRenderer`. This uses SkiaSharp to produce an image file. @@ -85,7 +121,7 @@ foreach (var plan in plans) } ``` -### 4. Serialization +### 5. Serialization To support binary serialization and handle special floating-point values (like `NaN` or `Infinity`) which are not standard in JSON, the library provides a helper class `PlanSerializer` using **MessagePack**.