HomeFeaturesExamplesTutorialsHelpTheoryVerificationPricingContact
BoreTherm / TutorialsTutorial 10 / 19
Workflow and theory · Layout & site

Site plan and linked drawing

How a drawing becomes a site plan, how boreholes are placed and checked on it, what the project stores and what stays linked, and what the positions do to the borefield. The numbers are those of the example project: an office building on an L-shaped plot of 1260 m² with two trees and a sewer, heated and cooled by a ground-source heat pump on 16 single-U boreholes of 150 m. The building needs 200 MWh of heating, 8 MWh of hot water and 45 MWh of cooling a year (monthly loads), and the field is simulated over 25 years.

01 / The one idea

The one idea: the drawing is a picture, the polygons are the rules

A DXF drawing (the exchange format of CAD programs) or a picture of the site is a background. BoreTherm does not calculate with it. What counts are the polygons made from it: drilling areas (where boreholes may go), no-go zones (buildings, trees) and corridors (pipes and cables in the ground), each with a setback (a margin no borehole may enter), in metres in the site frame. The boreholes are an ordinary custom field in the same frame.

1 The drawing (linked file, mm)2 The site plan (stored, metres)3 The field (stored, custom)Plot 1260 m2Buildinglayers → colours; $INSUNITS = 4 (mm)× 0.001 − origin; setbacks redheads; trench to the building
The example. The plot (green), the building and two trees (no-go zones, grey), the sewer (corridor, dashed blue) with their setbacks (red bands), the 16 heads and the trench to the building entry.
DXF → sitex = s · X − x0
Picture → sitew = a · z̄ + b
Region testc(p) ≥ 0
TrenchL = MST(heads, connection)

s is metres per drawing unit and x0 the origin; a and b (complex numbers: scale, rotation, shift) come from two points of a picture; c(p) is the free distance beyond the nearest setback; MST is the minimum spanning tree (the shortest set of straight trench runs that connects every head and the connection point at the building). The site frame has x to the east and y to the north and is the frame of the borehole heads. The thermal model does not know about the site: it sees only where the heads are.

02 / The workflow

The workflow

Plan view toolbardraw, CAD polyline, measurePlan tabload, store, units, placementAreas tabpolygons, setbacks, connectionCheck tabviolations per boreholeFill area… dialoggrid, staggered, row-wise, edge3D viewsite plan under the fieldResults and reportCalculate, Size boreholelength: site warning;report: site sectionCLIsite-check, fill, optimize --siteDesign › Field layout › Site planfilling, viewing, results, batch
Everything happens in the Site plan view of Field layout (next to Plan (2D) and 3D); the same site plan appears in the 3D view, in the results of Calculation › Calculate (the design check of the fluid temperatures) and Calculation › Size borehole length, and in the report.
Field layout › Site plan viewWhat plan do you have?DXF drawingLoad plan…: units from $INSUNITS(or Drawing units); far-offcoordinates shifted by an origin;Use layer as… / CAD polylinePicture: PNG, JPEG, SVG, PDFLoad plan…, then Set scale: twopoints with the real distanceand direction, or coordinates;draw the polygons on itNo plandraw drilling areas, no-gozones and corridors onthe grid of the plan view(coordinates in metres)Areas tab: kind and setback of each polygon,minimum borehole distance, connection pointIs there a field to keep?noyesFill area…pattern, spacing, row angle,count → preview → ApplyKeep the fieldmove heads in the plan;Check tab lists violationsCalculate / Size borehole lengtha site violation is a warning, not an errorSave: the plan stored in the project or linked;File › Pack project to send it
Three ways in, one way on. Every step is one undo step (Ctrl+Z): a polygon, a setback, a fill, the plan loaded or stored.
  • Layers to kinds. Use layer as turns every polyline of a layer into a polygon of the chosen kind; CAD polyline takes one polyline that you click. Closed polylines (also circles, closed splines and hatch loops) can be drilling areas or no-go zones; open ones only corridors or references. New polygons get default setbacks: drilling area 1 m, no-go zone 2 m, corridor 1.5 m. Change them in the Areas tab.
  • Fill area places heads in the drilling areas: grid, staggered (every other row shifted by half a spacing), row-wise (each row starts at the edge) or perimeter (along the edge only). With a count, the most spread-out heads are kept. Apply to the field replaces the field; the layout becomes Custom and the heads copy H, D, rb and tilt of the layout’s borehole.
  • Check lists every head outside an area, inside a no-go zone, within a setback, or closer to another head than the minimum distance. Calculate and Size borehole length still run; the results carry a site-plan warning.
03 / What is stored and what stays linked

What is stored and what stays linked

  • Stored in the project: the field, every polygon with its points in metres and its setback, the origin, the connection point, the minimum distance, and the background settings (type, path, units, hidden layers, opacity, calibration). With Store the plan, also a copy of the plan file; plans over 20 MB make the project large.
  • Linked: the plan file itself when no copy is stored. Save as rewrites the relative path for the new folder; File › Pack project puts the project and the linked plan into one zip. Send a pack, not a lone project file.
  • The polygons are copies, not live links. Changing the DXF later does not move them: use the layer again, or edit the polygons.
Project filefieldheads x, y; H, D, rb, tiltsite.polygonskind, name, points [m], setbacksiteorigin, connection point,minimum borehole distancesite.backgroundtype, path, units, hiddenlayers, opacity, calibrationsite.background.embedded (optional)a copy of the plan file: “Store the plan in the project”Plan drawing (DXF)the plan file (linked)relativepathGUI and reportdraw the plan: stored copyfirst, else the fileCore calculationsCalculate, Size borehole length,site-check, fill, optimizer:polygons and heads onlyA missing plan file costs only the picture: the polygons and the field stay valid.
The example links its drawing: the project keeps the path of the drawing, relative to the project file, and no copy. Loading a plan in the program stores a copy by default (Plan tab: Store the plan in the project).
04 / How it works

How it works

1 Read the DXFheader, layers, entities,blocks (INSERT)2 Tessellatearcs, circles, bulges in≤ 5° steps; splines3 To site metresx = s · X − x₀s from $INSUNITS4 Layers → polygonsclosed: area / no-go;any: corridor8 Field and checkscustom layout; sitecheck, trench, Calculate7 Choose Nspread-first order(or all positions)6 Filllattice at angle θ,offset searched5 Region testc(p) ≥ 0: inside anarea, clear of the restSteps 1–4 run once, when a layer or polyline is used. Steps 5–8 run for every fill and check.
From the drawing to a checked field. The fill keeps only positions that pass the region test, then thins them by the minimum distance in fill order.
  1. Reading. ASCII DXF, group code by group code: the header ($INSUNITS, extents), the layer table, blocks and entities. Lines, polylines with bulges, circles, arcs, ellipses, splines, hatch loops, points, texts and block references (with scale, rotation and arrays) are read; paper space and unknown entities are skipped with a note; binary DXF is refused.
  2. Units and origin. s comes from $INSUNITS (mm 0.001, cm 0.01, m 1, ft 0.3048, in 0.0254, …) unless a unit is chosen; a drawing without a unit is read in metres. Survey (UTM) coordinates in the millions would lose precision, so on loading BoreTherm shifts them by a round origin near the lower-left corner when it lies more than 10 km from 0.
  3. Region test. A point is inside a polygon by the winding number (any orientation, concave outlines). c(p) takes the best drilling area, then every no-go zone and corridor; 10⁻⁶ m tolerance, so a head exactly on a setback line is allowed.
  4. Fill. Rows run along the longest edge of the largest drilling area unless an angle is given. The lattice offset is searched on a 4 × 4 grid within one cell and the offset with the most positions wins.
05 / The theory

The theory: frames, the region test, and spacing

DXF: units and an origin, no rotationPicture: a similarity from two pointsX [mm]Y [mm](45000, 20000)× s− x₀x east [m]y north [m](45.0, 20.0) ms = metres per unit: $INSUNITS 4 = mm → 0.001;x₀ = origin, set when coordinates exceed 10 kmu [px]v [px]ABa z̄ + bx east [m]y north [m]a = scale · e^(iα) and b from A, B and theirreal distance and direction (or coordinates)
A DXF is placed by its unit and the origin only; it cannot be turned or moved in BoreTherm, so its +Y is north. A picture has no unit: two points with a known distance and direction (or known coordinates) fix scale, rotation and position, including the flip of the picture’s downward v axis.
Region test on the lower part of the plot (y < 21 m)ABCDc(p) = min over the rules of the free distancebeyond the setback; drill only where c ≥ 0A (3.0, 1.5)c = 0.50 m(drilling area)B (21.0, 7.5)c = −0.31 m(TREES)C (27.0, 1.5)c = 0.50 m(drilling area)D (24.0, 13.5)c = −0.50 m(SEWER)Open circles: the 6 m grid positions that pass.Red bands: the setbacks.
T-P14-1: c(p) = min( max over drilling areas [−dA − bA], min over no-go zones [dE − bE], min over corridors [distC − bC] ), d the signed distance to the outline (negative inside), b the setback. The name in brackets is the rule that decides.

The site plan has no thermal model of its own. It acts on the borefield only through the distances between the heads it allows: boreholes closer together take heat from each other, and the field gets colder over the years. The measure is Tf,min, the lowest mean fluid temperature (the mean of the inlet and outlet temperatures of the borehole fluid) over the simulated years; the design limit of the example is −3 °C.

Lowest fluid temperature of 16 boreholes, 150 m, the same loads246810121416−6−5−4−3−2−1014 × 4 grid at Bmean distance to the nearest neighbour [m]Tf,min [°C]limit −3 °Cspread 16 (example): −1.13 °Ccompact: −2.17 °CCloser boreholes take heatfrom each other: the fieldgets colder over the years.A site plan changes thethermal result only throughthe positions it allows.The grid squares: the same16 boreholes as a 4 × 4 grid(office example, CLI study).
The line: the same office as a 4 × 4 grid at spacing B (every head’s nearest neighbour is B away). The squares: two selections of 16 heads from the same 6 m fill of the example plot, placed at their mean nearest-neighbour distance.
The non-obvious part. The grid spacing of a fill is not the spacing of the field. The example fills the plot on a 6 m grid (28 positions) and keeps the 16 most spread out: their nearest neighbours are 7.15 m away on average, and Tf,min = −1.13 °C is close to a square grid at that distance. The 16 positions nearest the building entry, from the same fill, reach only −2.17 °C. A smaller plot, a tighter fill or a compact choice lowers the fluid temperature even when the borehole count and length stay the same.
06 / How each result is derived

How each result is derived

QuantityHow BoreTherm derives itExample
Drawing unit$INSUNITS of the DXF header, or the unit chosen under Drawing units; a drawing without a unit is read in metres$INSUNITS = 4 → mm, s = 0.001 m per unit
Site coordinatesx = s · X − x0, y = s · Y − y0; no rotation (the drawing’s +Y is north)plot corner (45000, 20000) → (45.0, 20.0) m
Originset on loading when the lower-left corner lies more than 10 km from 0 (rounded down to 1 m)(0, 0): the drawing is near 0
Circle → polygontessellated in steps of at most 5°tree r = 2.0 m → 72 points
Drilling areaarea of the drilling areas minus the no-go zones (setbacks not deducted)1260 m² → 1168.2 m²
Clearance of a headc(p) = the smallest free distance beyond a setback (T-P14-1)borehole 1 at (3.0, 1.5): 0.50 m (drilling area)
Fill capacitygrid at B = 6 m along the longest edge, lattice offset searched (4 × 4)28 positions, offset (3.0, 1.5)
Spread-first selectionfarthest-point order from the centroid; the first NN = 16: nearest neighbour 6.0 m min, 7.15 m mean
Trenchminimum spanning tree of the heads and the connection point (Prim)110.5 m
07 / The example in numbers

The example in numbers

Spread-first 16 (the example)Compact 16 (nearest the connection point)
The same 6 m fill (open circles), two ways to keep 16 heads. Orange: the trench, the minimum spanning tree to the connection point (square).
16 heads from the 6 m fillNeighbour min / mean [m]Tf,minTf,maxSized HDrillingTrench
Spread-first (example)6.0 / 7.15−1.13 °C16.42 °C130.0 m2080 m110.5 m
Compact, nearest the connection point6.0 / 6.00−2.17 °C16.08 °C141.2 m2258 m92.3 m

Tf at the example length of 150 m; sized H by Size borehole length; drilling = 16 × sized H. The spread field needs 179 m less drilling; the compact one 18 m less trench. Which one is cheaper depends on the prices: the optimizer (Optimization with region Site, or boretherm-cli optimize --site) ranks both kinds of selection by its cost function. Site check of the example: 0 of 16 heads with a problem; Calculate with the example loads: −1.13 °C to 16.42 °C.

08 / Limits to keep in mind

Limits to keep in mind

  • The drawing is only as good as its source. Check the unit, the scale (measure a known distance with Measure), north and the setbacks against the survey and the local rules. The example drawing is illustrative.
  • A DXF cannot be rotated in BoreTherm: the site frame takes the drawing’s axes. If the drawing is not north-up, directions in the project (the azimuth of inclined boreholes, the groundwater flow direction) refer to the drawing’s +X, not to east.
  • The check tests the heads only. Inclined boreholes can reach under a building or a neighbour’s plot below ground; look at the 3D view with the site plan shown.
  • A violation does not stop Calculate or Size borehole length. Read the warning and the Check tab before you report a design.
  • Setbacks are measured in the plan to the polygon outline. Two touching drilling areas keep their setbacks along the common edge: draw one polygon where drilling may cross.
  • Binary DXF, paper space and 3D solids are not read; export the plan view as ASCII DXF, or use a picture with a two-point scale.

Numbers calculated with BoreTherm. The fill, the site check, the sizing, the compact selection and the spacing study are made with boretherm-cli fill, site-check, size, simulate and study.