Methodology note · Roof geometry
1.1 million modeled roofs, and the error bars we keep.
TerritoryX carries a roof-size number for 1,099,910 Cook County parcels. Not one of them met a tape. This is the method behind that number: where the elevation data comes from, what the plane fitter throws out before it will believe a roof, why the county-wide figure carries a 1.54x correction, and the accuracy gate that has not opened yet.
1,099,910Parcels carrying a modeled roof sizeAssessor file · TerritoryX model
19.5Median modeled roof, in squaresTerritoryX model
1.54xCorrection applied to the records estimateRoof pipeline code
38,389Parcels whose story count falls to a defaultAssessor file
01 · The elevation layer
A DSM is a picture of the top of everything.
A digital surface model is a raster where every pixel carries the height of the topmost thing at that spot. Ridge line, chimney, satellite dish, and the neighbor's silver maple leaning over the garage. Its sibling, the digital terrain model, is the same grid stripped back to bare earth. Cook County has both, published by the Illinois Height Modernization Program from a 2022 collection at a one-foot pixel and served as an image service that answers point queries.
That last detail decided the architecture. Bulk point clouds for a county this size run to hundreds of gigabytes, so the sampler skips them entirely. It pulls the parcel polygon from the county's own parcel service, intersects it with the official 2022 building-footprint layer, lays a three-foot grid inside that intersection, and asks the elevation service for up to 1,200 samples. Fewer than 80 valid returns and it fits nothing.
The read for contractors
Elevation for this county is public and already paid for. Everything expensive happens downstream of the download, which is why a roof-size layer is worth judging on its error handling rather than its data source.
What the fitter is toldroof_cook_dsm_plane_sampler.py defaults
| Parameter | Default |
|---|---|
| Sample grid spacing | 3.0 ft |
| Max samples per footprint | 1,200 |
| Min samples to attempt a fit | 80 |
| Inlier threshold | 0.45 ft |
| Min inliers to keep a plane | 45 |
| RANSAC iterations | 650 |
| Max planes per building | 3 |
02 · Why footprint times pitch breaks
Divide, multiply, and be wrong by a factor of two.
The cheap way to size a roof from public records has three steps: take the assessor's building square footage, divide by stories to get a footprint, multiply by a pitch factor to get slope area. TerritoryX runs exactly that model, because it is the only thing that scales to a whole county. Most of the engineering effort then goes into the ways it lies.
Eligibility first. The model wants a building over 300 square feet and a non-zero assessed value, which admits 1,099,910 of the county's 1,114,335 residential parcels and drops 14,425. Median building size among the survivors is 1,501 square feet, quartiles at 1,143 and 2,236. Run the pipeline's own arithmetic across all of them and the median modeled roof lands at 19.5 squares, with quartiles of 16.0 and 24.2.
Now the failure. Dividing by stories means reading a text field, and text fields have edges. The lookup table in the scoring code maps nine labels to story counts. Cook writes its tall homes as "3 Story +", which is not one of the nine, so those parcels fall through to a 1.5-story default. There are 38,389 of them, 3.5% of the eligible set. Read at 1.5 stories, their median modeled roof is 47.6 squares. Read at 3.0, it is 23.8. Same house, same file, two defensible readings, a factor of two apart.
Living area carries a second bias. It excludes attached garages, porch roofs, and eave overhang, every square foot of which is still roof.
The read for contractors
A footprint model inherits every quirk of the categorical field driving it. Before you trust anyone's roof size off public records, ask what their code does with the homes their lookup table has never heard of.
Story labels on the assessor fileAssessor · n=1,099,910 eligible parcels
03 · What the fitter refuses
Walls and tree canopy look exactly like very steep roofs.
Given a cloud of elevation samples inside a footprint, the fitter uses RANSAC. Draw three points at random, solve the plane through them, count how many of the remaining points sit within 0.45 feet of it, keep the best of 650 draws, and accept the winner only if it holds at least 45 points. Strip those points out and run it again, up to three planes per building.
Left alone, that procedure fails in a specific and nasty way. Samples inside a footprint are not all roof. A wall face caught at the footprint edge, or a canopy overhanging the eave, produces a dense band of points that a near-vertical plane fits beautifully, and it wins the inlier contest against the real roof plane. The code comment records the rate before the fix at roughly 58% of fits landing on an artifact instead of a roof.
The correction is a cap. Residential roofs top out around 12/12, which is 45 degrees, so any candidate plane steeper than 50 degrees gets rejected during sampling and again after the final refit on inliers. There is deliberately no floor. A flat roof is a real roof, and a near-zero slope is a legitimate answer.
The instructive part is what did not work. Filtering points by height above ground before fitting is the obvious hygiene step, and it was built and tested. It cut the pass rate from 81% to 50%, because it starved footprints of the points the fit needed. The revert note sits in the sampler with its date on it. The bottleneck was never point quality.
The read for contractors
Anyone can show you a plane fit on a clean gable. Ask what the fitter does with a mature oak over the eave, and whether they can quote you their own artifact rate. A vendor who has never measured that number has not looked.
Modeled roof size, county-wideTerritoryX model · n=1,099,910
04 · Calibration
The correction factor is 1.54, and the code calls it provisional.
Plane fitting runs on a sample of parcels. The county-wide roof size is the records model. So the two have to be tied together, and the direction of the tie is itself the finding: the records estimate ran low. Across the 26-roof calibration set, the median ratio of records estimate to LiDAR fit was 0.65, roughly 35% light. That is where the 1.54x constant in the pipeline comes from. Garage, porch, and overhang, exactly as the theory predicted. The comment next to the constant calls it provisional on a small, QA-pending sample, and it stays labelled that way in every report the pipeline writes.
There is a second gate above that one, and it has not opened. A separate harness compares LiDAR-fit geometry against premium ground-truth reports from the commercial vendors contractors already buy. It passes only if median absolute error on squares is at or under 10.0%, median absolute pitch error is at or under 5.0 degrees, and at least 5 parcels match. A pass still flips nothing on its own: the harness writes a markdown report, never touches the database, and leaves the decision to a person. Today it runs against a template file whose every row is stamped illustrative. No real vendor report has gone in yet.
The read for contractors
Until that harness runs on real vendor reports at county scale, every roof size here is an internal estimate for review. We would rather publish the limit than sell a precision we have not earned.
The calibration gateroof_calibration_harness.py thresholds
| Condition | Must be |
|---|---|
| Median absolute squares error | 10.0% or less |
| Median absolute pitch error | 5.0 deg or less |
| Matched parcels | 5 or more |
| Ground truth used so far | Template only |
05 · The error bars
Good enough to rank a territory. Not good enough to quote one.
Every candidate row the pipeline writes carries three flags in the same insert: an external-claim flag hard-set to 0, a review status of internal review required, and an upgrade action naming visual QA or a premium report before the number goes anywhere near a quote. Confidence is capped at 0.88 by construction, area confidence at 0.78, and 0.78 is also the line below which the geometry normalizer refuses to call any measurement customer-safe.
Even a clean, high-confidence fit grades out short, and for a structural reason rather than a tuning one. A surface model hands you area and pitch. It says nothing about ridge, hip, valley, eave, or rake length, and without those linears there is no material order at the end of it.
So what is the layer actually for? Distribution. Modeled sizes spread the way a century-old housing stock should: 18.5% under 15 squares, 35.3% between 15 and 20, 23.8% between 20 and 25, 7.5% between 30 and 40, and 5.3% above 40. In a county where 89.4% of roofs are asphalt shingle on the assessor's file, roof size is one of the few variables that separates a small repair market from a full-replacement one, and it holds up well enough across a whole neighborhood to rank neighborhoods with. That is the claim being made here: aggregate ordering, not per-home precision.
Read a modeled roof size the way a broker reads a comp. It tells you which blocks are worth a truck roll on a Tuesday.
The read for contractors
Rank with the model, price with the tape. A roof-geometry layer earns its keep by telling you where to spend the day, never what to charge for it.
Confidence ceilings in the codeRoof pipeline defaults
| Field | Value |
|---|---|
| Max fit confidence | 0.88 |
| Max area confidence | 0.78 |
| Customer-safe floor | 0.78 |
| External claim allowed | 0 |
Method & sources
Parcel counts and size distributions are computed from the Cook County Assessor's property-characteristics file as staged by TerritoryX, covering 1,114,335 residential parcels. The modeled roof-size figures apply the production formula to the 1,099,910 parcels that meet the model's eligibility rule (building over 300 square feet, assessed value above zero): assessor building square footage divided by a story count, multiplied by a typical-pitch factor of 1.15, multiplied by the 1.54 records calibration, divided by 100 to give squares. Story counts come from the assessor's residence-type label; parcels whose label is absent from the lookup table take a 1.5-story default, which is stated here rather than smoothed over. Percentages are shares of parcels with the relevant field populated, and the roof-material share uses the 1,114,270 parcels with that field non-empty.
Elevation figures describe the Illinois Height Modernization Program's 2022 Cook County surface and terrain models, sampled through their public image services inside official county parcel and 2022 building-footprint geometry. Fitter parameters, the pitch cap, the artifact rate, the calibration constant, and the gate thresholds are read directly from the TerritoryX roof pipeline source: the DSM plane sampler, the LiDAR plane fitter, the geometry normalizer, and the calibration harness.
Everything on this page is aggregate. No individual home is identified, no roof condition is claimed or inferred, and no per-home geometry is published. Roof sizes are modeled from public LiDAR and public county records, remain internal estimates for contractor review, and stay that way until a county-level calibration pass against real ground-truth reports is completed and published.
Cook County Assessor · building characteristics
Illinois Height Modernization Program · 2022 DSM & DTM
Cook County GIS · parcels & 2022 building footprints
TerritoryX roof pipeline · fitter, normalizer, calibration harness
Want this run on the towns you actually work?
The Territory X-Ray applies the same modeled geometry, stock age, storm cohort, permit suppression, and ownership layers to your service area, then ranks the neighborhoods and picks the first campaign. Start with the free county read on the Territory Intelligence hub.
Request a Territory X-Ray