floorplan-api 0.5.0__tar.gz → 0.6.0__tar.gz

{floorplan_api-0.5.0 → floorplan_api-0.6.0}/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to `floorplan-api` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-10-02
+
+### Changed (breaking)
+- **`extract`, `analyze` and `upload_then_extract` return a `Result`**
+  instead of `MaskBytes` (sync and async clients). One call now gives the
+  wall mask and the structured result:
+  - `result.wall_mask`: the PNG wall mask, still a `MaskBytes` (`bytes`
+    with `width`, `height`, `job_id`, `request_id`, `mode`, `page_size_pt`,
+    `pdf_scale`, `pdf_dpi`). Code that wrote the return value to a file now
+    writes `result.wall_mask`.
+  - `result.room_mask`: PNG bytes where each pixel holds a room `id`
+    (0 = no room), or `None`.
+  - `result.detections`: doors and windows as `Detection` (`label`,
+    `confidence`, `polygon`, `center`, `size`); `result.doors` and
+    `result.windows` filter by label. `label` is the JSON `class` key.
+  - `result.rooms`: `Room` objects (`id`, `score`, `area`, `polygon`, plus
+    `outline` and `holes`).
+  - `result.counts`, `width`, `height`, `page`, `dpi`, `min_room_score`,
+    `job_id`, `request_id`, `mode`, `page_size_pt`, and `raw` (the JSON
+    response without the masks).
+
+  All coordinates are pixels on the wall mask's grid.
+- **`download_mask(job_id)` is replaced by `get_result(job_id)`**, which
+  returns the same `Result` for a completed job. There is no alias. After a
+  `TimeoutError` with `job_id`, recover with `wait_for_job` + `get_result`.
+- `Job.result.result_url` now points at the job's result
+  (`/v1/jobs/{job_id}/result`).
+- `MaskBytes.from_response` is replaced by `MaskBytes.from_result`: mask
+  `width` / `height` now come from the response body; the `X-Mask-Width` /
+  `X-Mask-Height` headers are no longer sent.
+- A successful response without a usable wall mask raises `ServerError`.
+
+### Added
+- `Result`, `Detection` and `Room` are exported from `floorplan_api`.
+- **`min_room_score=`** on `extract`, `analyze` and `analyze_async` (sync and
+  async clients): the room-score floor, a number from 0 to 0.9 (server
+  default 0.9). Every room carries a `score`: 1.0 for a fully enclosed room;
+  lower values for rooms the service had to close itself. Rooms scoring
+  below `min_room_score` are not returned. Values outside 0–0.9 raise
+  `InvalidRequestError` before any request.
+
 ## [0.5.0] - 2026-09-25
 
 ### Added

{floorplan_api-0.5.0 → floorplan_api-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: floorplan-api
-Version: 0.5.0
-Summary: Official Python client for the Floor Plan API — wall-segmentation masks from floor plan images and PDFs.
+Version: 0.6.0
+Summary: Official Python client for the Floor Plan API — walls, doors, windows and rooms from floor plan images and PDFs.
 Project-URL: Homepage, https://floorplanapi.com
 Project-URL: Documentation, https://floorplanapi.com/docs
 Project-URL: Changelog, https://floorplanapi.com/docs#python-changelog
@@ -44,11 +44,12 @@ Description-Content-Type: text/markdown
 # floorplan-api
 
 Official Python client for the [Floor Plan API](https://floorplanapi.com):
-upload a floor plan, get back a binary wall-segmentation PNG mask.
+upload a floor plan, get back its walls, doors, windows and rooms.
 
-* **Image in, image out.** PNG, JPEG, WEBP, or one page of a PDF. The mask
-  comes back as PNG bytes at the input's resolution: `255` = wall, `0` =
-  everything else.
+* **One call, everything.** PNG, JPEG, WEBP, or one page of a PDF in; a
+  `Result` out: the wall mask as PNG bytes at the input's resolution
+  (`255` = wall, `0` = everything else), the doors and windows as oriented
+  boxes, and the rooms as polygons plus a room mask.
 * **Two clients, one surface.** `Client` (synchronous, on `requests`) and
   `AsyncClient` (asyncio, on `httpx`).
 * **Retries that don't double-bill.** Transient failures are retried with
@@ -72,20 +73,83 @@ Python 3.9+.
 from floorplan_api import Client
 
 client = Client(api_key="fp_test_...")            # or set FLOORPLAN_API_KEY
-mask = client.extract("plans/floor1.png")         # PNG, JPEG or WEBP
-mask = client.extract("plans/set.pdf", page=3)    # PDF: pick the page
+result = client.extract("plans/floor1.png")       # PNG, JPEG or WEBP
+result = client.extract("plans/set.pdf", page=3)  # PDF: pick the page
 
 with open("walls.png", "wb") as fh:
-    fh.write(mask)
+    fh.write(result.wall_mask)                    # the PNG wall mask
 
-print(mask.width, mask.height, mask.job_id)
+print(result.width, result.height, result.job_id)
+print(len(result.rooms), "rooms,", len(result.doors), "doors,", len(result.windows), "windows")
 ```
 
-`extract()` returns `MaskBytes`, a `bytes` subclass. Write it, hash it, hand
-it to Pillow or OpenCV as usual; the extra attributes `width`, `height`,
-`job_id`, `request_id` and `mode` (`live`/`test`) come from the response
-headers. For a PDF, `page_size_pt` and `pdf_scale` are attached too (see
-below). The client never post-processes the mask.
+## The result
+
+`extract()`, `analyze()`, `upload_then_extract()` and `get_result()` return a
+`Result`. Everything in it shares one pixel grid: the decoded input image,
+or the rendered PDF page. The origin is the top-left corner.
+
+| Attribute | What it is |
+| --- | --- |
+| `wall_mask` | The wall mask: PNG bytes, 8-bit single-channel, `255` = wall, `0` = everything else. A `MaskBytes` (see below). |
+| `room_mask` | PNG bytes where each pixel holds the `id` of its room (`0` = no room); 8-bit, or 16-bit when there are 255 or more rooms. `None` when the service produced no rooms output. |
+| `detections` | Doors and windows, a list of `Detection`. `result.doors` and `result.windows` are the same list filtered by label. |
+| `rooms` | A list of `Room`. |
+| `counts` | Items per kind, e.g. `{"door": 12, "window": 11, "room": 11}`. May be empty. |
+| `width`, `height`, `size` | The pixel grid. |
+| `page`, `dpi` | The PDF page that was processed and the resolution it was rendered at. `dpi` is `None` for raster input. |
+| `min_room_score` | The room-score floor that was applied (or `None`). |
+| `job_id`, `request_id`, `mode` | The job, the request ID for support tickets, and `live`/`test`. |
+| `page_size_pt` | For a PDF you passed as a file: the page size in PDF points (see below). |
+| `raw` | The decoded JSON response without the two base64 masks, ready for `json.dump`. |
+
+```python
+for door in result.doors:
+    door.label        # "door" or "window" (the JSON key is `class`)
+    door.confidence   # 0 to 1
+    door.polygon      # the 4 corners of the oriented box: [(x, y), ...]
+    door.center       # (x, y)
+    door.size         # (width, height) along the box's own axes
+
+for room in result.rooms:
+    room.id           # 1, 2, ...: the pixel value of this room in result.room_mask
+    room.score        # 1.0 for a fully enclosed room; lower values for rooms
+                      # the service had to close itself
+    room.area         # in square pixels
+    room.outline      # the outer ring: [(x, y), ...], no closing point
+    room.holes        # rings cut out of the room
+    room.polygon      # [outline, *holes]
+```
+
+`result.wall_mask` is a `MaskBytes`, a `bytes` subclass. Write it, hash it,
+hand it to any image library as usual; it also carries `width`, `height`,
+`job_id`, `request_id`, `mode` and, for a PDF, `page_size_pt` and
+`pdf_scale`. The client never post-processes either mask.
+
+```python
+import io, json
+import numpy as np
+from PIL import Image
+
+walls = np.array(Image.open(io.BytesIO(result.wall_mask)))       # 0 / 255
+if result.room_mask is not None:
+    room_ids = np.array(Image.open(io.BytesIO(result.room_mask)))  # 0 = no room
+    kitchen = room_ids == result.rooms[0].id
+
+json.dump(result.raw, open("plan.json", "w"))                    # everything but the masks
+```
+
+### Choosing which rooms you get
+
+Every room carries a `score`: 1.0 for a fully enclosed room; lower values
+for rooms the service had to close itself. `min_room_score=` (0 to 0.9,
+server default 0.9) sets the floor: rooms scoring below it are not returned.
+
+```python
+result = client.extract("plan.png", min_room_score=0.5)   # a lower floor returns more rooms
+```
+
+## Inputs
 
 Any of these inputs work:
 
@@ -120,35 +184,38 @@ does not slice, then call `extract(upload_key=..., page=N)`.
 A PDF is processed one page at a time. Pass `page=` (1-based; default 1) to
 say which. Page errors (out of range, password-protected, unreadable) are
 raised as `InvalidRequestError` before anything is sent. The API rasterises
-the page at 200 DPI (longest edge capped at 8192 px) and returns the mask
-at that size; read it from `mask.width` and `mask.height`.
+the page at 200 DPI (longest edge capped at 8192 px) and returns the result
+on that grid; read it from `result.width`, `result.height` and `result.dpi`.
 
 ```python
-mask = client.extract("set.pdf", page=3)
+result = client.extract("set.pdf", page=3)
 key = client.upload("set.pdf", page=3)        # the stored object is page 3 only
-mask = client.extract(upload_key=key)         # ... so no page is needed here
+result = client.extract(upload_key=key)       # ... so no page is needed here
 ```
 
 `page` on a raster input is rejected unless it is 1. When you submit by
 `upload_key` for an object you stored yourself (raw REST), `page=` is sent
 to the server, which renders that page of the stored file.
 
-**Mapping the mask back to PDF coordinates.** The mask is on the rendered
-page's pixel grid, not in PDF points. The client measures the page's crop
-box (honouring `/Rotate`) before upload and attaches it, so:
+**Mapping the result back to PDF coordinates.** The masks, detections and
+rooms are on the rendered page's pixel grid, not in PDF points. The client
+measures the page's crop box (honouring `/Rotate`) before upload and
+attaches it, so:
 
 ```python
-mask = client.extract("set.pdf", page=3)
-mask.page_size_pt      # (1728.0, 2592.0)  -> a 24 x 36 in sheet
-mask.pdf_scale         # mask pixels per PDF point: mask.width / page width
+result = client.extract("set.pdf", page=3)
+result.page_size_pt    # (1728.0, 2592.0)  -> a 24 x 36 in sheet
+mask = result.wall_mask
+mask.pdf_scale         # pixels per PDF point: mask.width / page width
 mask.pdf_dpi           # the DPI actually used: 200, or less if the page hit the 8192 px cap
 
-x_px = x_pt * mask.pdf_scale   # PDF point -> mask pixel (origin: top-left of the render)
+x_px = x_pt * mask.pdf_scale   # PDF point -> pixel (origin: top-left of the render)
+outline_pt = [(x / mask.pdf_scale, y / mask.pdf_scale) for x, y in result.rooms[0].outline]
 ```
 
 `floorplan_api.pdf_page_size(data, page)` gives the same `(width, height)`
-in points for any PDF, for example to compute the scale for a mask you
-fetched later with `download_mask()`, which has no `page_size_pt`.
+in points for any PDF, for example to compute the scale for a result you
+fetched later with `get_result()`, which has no `page_size_pt`.
 
 ### Async
 
@@ -158,12 +225,12 @@ from floorplan_api import AsyncClient
 
 async def main() -> None:
     async with AsyncClient() as client:
-        masks = await asyncio.gather(
+        results = await asyncio.gather(
             client.extract("a.pdf"),
             client.extract("b.png"),
         )
-        for m in masks:
-            print(m.size)
+        for r in results:
+            print(r.size, len(r.rooms))
 
 asyncio.run(main())
 ```
@@ -179,11 +246,11 @@ presigned upload for anything bigger, so the API server never holds the
 bytes:
 
 ```python
-mask = client.upload_then_extract("big_floor_plan.pdf", page=2)
+result = client.upload_then_extract("big_floor_plan.pdf", page=2)
 
 # or step by step:
 key = client.upload("big_floor_plan.pdf", page=2)   # PUT straight to object storage
-mask = client.extract(upload_key=key)               # submit by storage key
+result = client.extract(upload_key=key)             # submit by storage key
 ```
 
 The size check happens after the page is cut out, so a large multi-page PDF
@@ -193,26 +260,24 @@ whose selected page is small still takes the inline path.
 
 ## What the API does with your file
 
-Nothing on the client or the API server touches pixels; the worker does,
-like this (the full trace is in `docs/IMAGE_PIPELINE.md` of the API repo):
+The client never touches pixels. This is how the service reads your file
+and what the result is aligned to:
 
-* **Rasters** are decoded with OpenCV in colour mode. Alpha is dropped
-  without compositing, so flatten transparent PNGs onto white first;
-  grayscale is expanded to three channels; 16-bit depth becomes 8-bit; JPEG
-  EXIF orientation is applied, so the mask aligns with the *displayed*
-  orientation; ICC profiles are ignored. A raster whose longer edge exceeds
-  8192 px is processed downscaled to that bound and the mask is resized back
-  to the input size, so it stays pixel-aligned but carries less detail.
+* **Rasters.** Alpha is dropped without compositing, so flatten transparent
+  PNGs onto white first; grayscale is expanded to three channels; 16-bit
+  depth becomes 8-bit; JPEG EXIF orientation is applied, so the result
+  aligns with the *displayed* orientation; ICC profiles are ignored. A
+  raster whose longer edge exceeds 8192 px is processed downscaled to that
+  bound and the result is mapped back to the input size, so it stays
+  pixel-aligned but carries less detail.
 * **PDF pages** are rendered at 200 DPI onto white (transparent regions
   composite onto white), reduced so the longer edge is at most 8192 px. All
-  content is rendered: linework, hatching, text, dimensions. The mask has
-  the rendered size, reported in `width`/`height`.
-* **Inference** is a two-stage U-Net++ (whole sheet at shortest side 1024,
-  then a crop refiner at native resolution). No test-time augmentation.
-* **Output** is `prob > 0.5` as an 8-bit single-channel PNG with values
-  exactly 0 and 255, no morphology or filtering. `255` is wall in the
-  *carved* convention: door and window openings are not wall, and walls are
-  as thick as the source linework.
+  content is rendered: linework, hatching, text, dimensions. The result is
+  on the rendered grid, reported in `width`/`height`/`dpi`.
+* **Wall mask.** An 8-bit single-channel PNG with values exactly 0 and 255.
+  `255` is wall in the *carved* convention: door and window openings are
+  not wall, and walls are as thick as the source linework.
+* **Doors, windows and rooms** are on the same pixel grid as the wall mask.
 
 Limits you will meet: inline uploads 10 MB; presigned URLs valid 15 min;
 beta and Free keys 10 requests per minute; the sync endpoints wait 30 s for
@@ -236,7 +301,7 @@ client = Client()
 
 ## Background jobs
 
-For batches, submit a job and collect the mask later:
+For batches, submit a job and collect the result later:
 
 ```python
 job = client.analyze_async("plan.png")
@@ -244,8 +309,8 @@ print(f"Submitted {job.id}, status={job.status}")
 
 final = client.wait_for_job(job.id, poll_interval=2.0, timeout=300.0)
 if final.status == "completed":
-    mask = client.download_mask(final.id)
-    print(f"got {final.result.width}x{final.result.height} mask")
+    result = client.get_result(final.id)
+    print(f"got {result.width}x{result.height}, {len(result.rooms)} rooms")
 
 # Or poll yourself:
 job = client.get_job(job.id)
@@ -255,7 +320,7 @@ if job.is_terminal:
 
 `analyze` and `extract` currently produce identical output; the two
 endpoints are kept distinct so future tiers can attach to `analyze`
-without breaking `extract`'s simpler contract.
+without changing `extract`.
 
 ## Timeouts on a busy queue
 
@@ -269,12 +334,12 @@ resubmitting:
 from floorplan_api import TimeoutError
 
 try:
-    mask = client.extract("plan.pdf")
+    result = client.extract("plan.pdf")
 except TimeoutError as exc:
     if exc.job_id is None:
         raise                                   # client-side timeout
     job = client.wait_for_job(exc.job_id)
-    mask = client.download_mask(job.id)
+    result = client.get_result(job.id)
 ```
 
 ## Errors
@@ -290,7 +355,7 @@ from floorplan_api import (
 )
 
 try:
-    mask = client.extract("plan.png")
+    result = client.extract("plan.png")
 except RateLimitError as exc:
     time.sleep(exc.retry_after or 5.0)
 except ProcessingError as exc:
@@ -304,12 +369,13 @@ except FloorPlanError as exc:
 | Exception | Status | When | Retried |
 | --- | --- | --- | --- |
 | `AuthenticationError` | 401, 403 | Missing/invalid/expired/revoked key; job belongs to another account | no |
-| `InvalidRequestError` | 400, 409, 413, 415 | Malformed body, bad `page`, mask requested before completion, file too large, unsupported type. Also raised locally for unsupported input or a PDF page that does not exist | no |
+| `InvalidRequestError` | 400, 409, 413, 415 | Malformed body, bad `page`, result requested before completion, file too large, unsupported type. Also raised locally for unsupported input or a PDF page that does not exist | no |
 | `NotFoundError` | 404 | Job/resource missing | no |
 | `RateLimitError` | 429 | Per-minute rate limit exceeded | yes, honouring `Retry-After` |
 | `TimeoutError` | 504 | Worker did not finish in the sync window; `job_id` set | no |
 | `ProcessingError` | 500 | Worker failed the job (undecodable file, ...); `job_id` set | no |
 | `ServerError` | other 5xx | Outage, queue at capacity (503 honours `Retry-After`) | yes |
+| `ServerError` | — | A successful response that does not carry a usable result (no wall mask) | no |
 | `TimeoutError` | — | Client-side `timeout` exceeded, or `wait_for_job` gave up | connection timeouts yes |
 | `ConnectionError` | — | DNS / TCP / TLS failure | yes |
 
@@ -359,7 +425,7 @@ See [`examples/`](./examples/):
 
 * [`quickstart.py`](examples/quickstart.py) — extract a single image or PDF
 * [`async_client.py`](examples/async_client.py) — extract several files concurrently
-* [`async_job.py`](examples/async_job.py) — submit + poll + download
+* [`async_job.py`](examples/async_job.py) — submit + poll + fetch the result
 * [`sync_timeout_recovery.py`](examples/sync_timeout_recovery.py) — finish a job after a 504
 * [`local_dev.py`](examples/local_dev.py) — talk to a local dev server