Excel template Excel example

Log layout

Choose the columns of this log, their order, widths and headings, or add your own. The preview updates as you go; the layout is saved with this log.

Column widths

Widths are relative: the columns share the log's width in proportion.

ShowColumnHeadingWidthOrder

Add a column

Hatches and sampler symbols

Draw a layer with your own hatch, or a sample with your own symbol, from a PNG, JPG or SVG image. Follow the steps below; you don't need to edit the JSON yourself.

In this log

No custom hatches or sampler symbols yet.

1. What is it?

2. Choose the image

Image

3. Choose the layers that use it

What this changes in the JSON


        

Hatches are saved in this log's JSON, not on the server. To use one in API requests or in another log, copy its "patterns" section: see using your own hatches with the API.

Built-in codes

These already exist. Replace puts your own image in place of a USCS hatch or sampler symbol everywhere in this log. Use draws the layers you tick with one of the built-in materials; no image is needed.

Soil hatches (USCS symbols)
Other materials and rock (fill, asphalt, sandstone, granite…)
Sampler symbols

NoRecovery is not a sampler symbol. A sample with that type (or "NR" or "No recovery" as its type or number) is accepted with a warning, drawn as Other, and noted as "No recovery" in the remarks. Better: give the sampler that was tried as its type and set "recovery_percent": 0.

JSON format

A boring log is one JSON object. Only layers is required (schema_version is optional; the latest version is assumed). Depths are measured down from the ground surface. Fields set to null are treated as missing. A misspelled field name is reported as an error, so typos don't go unnoticed.

{
  "schema_version": "1.0",
  "units": { "length": "m", "unit_weight": "kN/m3", "diameter": "mm" },
  "metadata": { "boring_name": "B-1", "site_name": "…", "latitude": 34.07, "longitude": -118.44,
                "elevation": 120.5, "start_date": "2024-05-01", "boring_type": "Hollow-stem auger",
                "rig": "…", "diameter": 200, "hammer": "Automatic", "energy_ratio": 80, "logged_by": "…" },
  "groundwater": [ { "depth": 4.2, "date": "2024-05-01", "note": "encountered" } ],
  "layers": [
    { "top": 0, "bottom": 3.5, "description": "Brown, loose, moist, silty SAND", "uscs": "SM" }
  ],
  "samples": [
    { "top": 1.5, "bottom": 1.95, "name": "S-1", "type": "SPT", "blow_count": 8,
      "specimens": [ { "name": "S-1A", "top": 1.6, "bottom": 1.75, "water_content": 18.2, "fines_content": 24 } ] }
  ]
}
units
length: m or ft. unit_weight: kN/m3 or pcf. diameter: mm, cm, m, in or ft. Metric is the default.
layers[]
top, bottom, description, uscs (e.g. SM or SP-SM), and hatch to choose the graphic log pattern: a USCS symbol, a built-in material such as FILL, ASPHALT, SANDSTONE or GRANITE (all 67 are listed in the Hatches… window), or your own ("none" leaves it blank). Without hatch, a material or rock named as the principal material in the description is drawn, such as fill (also "FILL: silty sand" or "(hydraulic fill)"), asphalt, topsoil, no recovery or shale, ahead of the USCS symbol; otherwise, without uscs, the pattern is guessed from the description, and when the description determines a USCS symbol (e.g. "fat CLAY" or "(SP-SM)"), it is shown in parentheses. A recorded uscs that isn't a possible symbol (such as GW-GP) or that differs from the symbol the description determines (SP-SM on a "well graded SAND") gets a warning, and the symbol read from the description is shown below it in parentheses: SP-SM (SW).
samples[]
top, bottom, name, type (SPT, ModCal, DamesMoore, Shelby, Piston, Osterberg, Pitcher, Denison, LargeDiameter, Block, DirectPush, GelPush, Sonic, Core, TripleTube, Bulk, Grab, Composite, Auger, Trench, Disturbed, Other, and NoRecovery, which is accepted with a warning and noted as "No recovery" in the remarks; the Hatches… dialog shows each symbol), blow_count (a number, or text such as "50/5in"), blows (per increment, e.g. [6, 8, 10]), energy_ratio, sampler_diameter, recovery_percent, total_unit_weight and dry_unit_weight (of the whole sample), remarks (a sample has remarks, not a description), specimens. recovery_percent is the recovery as a percent of the sample length and is noted in the remarks ("Recovery 80%"); use "recovery_percent": 0 for no recovery and keep the sampler that was tried as type. An older recovery length is converted to a percent, with a warning.
samples[].specimens[]
The specimens tested in the laboratory, as in NGL (SPEC, with its INDX and PLAS results): name, top, bottom, water_content, total_unit_weight, dry_unit_weight, specific_gravity, fines_content, liquid_limit, plastic_limit, nonplastic, uscs (from the lab classification; shown in the Lab USCS column), remarks. Each is drawn as a box over its depth range in the Specimen column, with its name and results on a row level with it. A specimen without top gets no box and its results are shown level with the sample; with top only, it is drawn at that depth. Lab results put on the sample itself are shown the same way, with a warning (except unit weights, which may be given for a whole sample).
groundwater[]
depth, date, note.
depth_notes[]
depth and description: an observation at one depth within a layer, drawn in italics in the material description column.
layout
How the log is laid out: width (px), font_size, and columns, the columns in order. Each is a column id or an object with id, a relative width (the columns share the log's width in proportion) and a label. A new id with "source": "sample" or "specimen" shows each sample's or specimen's custom value ("custom": { "pocket_pen": 1.5 }; field names the key if it isn't the id, decimals rounds numbers), and "source": "blank" adds an empty column. You don't need to write this by hand: the Layout… window sets all of it, including the values of custom columns.
references[]
text and url: the sources of the data (e.g. the report the boring comes from), listed in the header above the log; an http(s) url is a link in the SVG.
patterns
Your own graphic log patterns and sampler symbols, by code: { "FILL": { "name": "Fill", "svg": "<svg viewBox='0 0 40 20'><line x1='0' y1='20' x2='40' y2='0' stroke='black'/></svg>" } }, as SVG markup (drawing elements only: path, rect, circle, ellipse, line, polyline, polygon, g), or as a picture: "image": "data:image/png;base64,…" with "width" and "height" in px. Add "kind": "sampler" for a sampler symbol, and tile_width (px) to change the tile size. A USCS code or built-in sampler name replaces the built-in pattern. The Hatches… button builds these entries from an image file and applies them to the layers or samples you pick. They are saved in the JSON, not on the server; to use them with the API, see using your own hatches with the API.

The complete definition is in the JSON Schema.

Excel workbooks

Instead of writing JSON, you can fill in the Excel template and open it with Open files… (or drop it on the editor). One workbook holds one boring; it is converted to the JSON format in the editor, so you can check, edit and download it as usual. The workbook is read in your browser and is not uploaded.

Each sheet is one part of the JSON: Units, Metadata, Layers, Samples, Specimens, Groundwater, Depth notes, References, Layout and Columns. The table sheets have one row per layer, sample and so on, under a header row of field names (the names used in the JSON); the Units, Metadata and Layout sheets have a field name in column A and its value in column B. The rows of explanation above each header row (units, allowed values) can be deleted: the header row is found by its field names. Specimens are put with their sample by the sample name in their sample_name column. Extra columns on the Samples and Specimens sheets become custom values, which the Columns sheet can show. Filled-in examples: B-3-example.xlsx (the coastal example: layers, SPT samples, lab specimens with Atterberg limits and unit weights, groundwater) and NAS-1.xlsx (a real boring from Nantou, Taiwan).

API

To render from a script or another website, send the JSON (or an AGS4 or DIGGS file) as the body of a POST request to https://uclageo.com/boring-log-viewer/api/render with Content-Type: application/json. The response is the log as SVG (the default), PNG or an HTML page.

curl -X POST -H "Content-Type: application/json" --data-binary @boring.json \
     "https://uclageo.com/boring-log-viewer/api/render?format=png&units=ft" -o boring.png
import requests
with open("boring.json") as f:
    r = requests.post("https://uclageo.com/boring-log-viewer/api/render",
                      params={"format": "svg"}, data=f.read(),
                      headers={"Content-Type": "application/json"})
r.raise_for_status()
open("boring.svg", "w", encoding="utf-8").write(r.text)
format
svg, png or html. Without it, the Accept header decides, and SVG is the default.
Drawing options
units (m or ft), width (px), header, legend, fit_text and hide_empty_columns (true or false), columns (a comma-separated list, e.g. depth,graphic,description,blow_count), title, font_size, height, scale.
Output options
png_scale (0.5 to 4, default 2), download=true (asks the browser to save the file instead of showing it).
Errors
Errors come back as JSON: { "error": "…", "errors": [{ "path": "/layers/2/uscs", "message": "…" }] }. Status 400 means malformed JSON or a bad query parameter, 422 an invalid boring log, and 429 more than 60 requests per minute. Warnings, such as gaps between layers, don't stop rendering and are returned in the X-Boring-Log-Warnings header.
Other endpoints
POST api/validate returns { valid, errors, warnings }. GET api/schema returns the JSON Schema, and GET api/health reports whether the service is up.

AGS4 and DIGGS files

An AGS4 file can be sent as it is, with Content-Type: text/plain. It is converted to the JSON format (strata, samples, SPT results, water content, Atterberg limits, fines, densities and water strikes) and drawn; add loca_id to choose the borehole when the file has more than one. POST api/ags returns the converted JSON for every borehole instead, for editing or checking. The same conversion runs on this page when you open an .ags file.

DIGGS XML files (2.5, 2.6 and 3.x) work the same way: send one with Content-Type: application/xml to api/render (with loca_id for the borehole name) or to api/diggs for the converted JSON, or open it on this page. Strata come from the lithology observations, samples from the sampling activities, and SPT and laboratory values from the test results. Files may be up to 10 MB.

curl -X POST -H "Content-Type: text/plain" --data-binary @site.ags \
     "https://uclageo.com/boring-log-viewer/api/render?loca_id=BH01&format=png" -o BH01.png

Requests are limited to 1 MB of JSON (10 MB for AGS4 and DIGGS files), 2,000 layers and 5,000 samples. Submitted data is not stored.

Using your own hatches with the API

Hatches and sampler symbols you make on this page are not stored on the server. They are saved inside the log's JSON, in a section called "patterns": as SVG markup, or, for a hatch kept as a picture, as a long line of encoded text. The API draws a custom hatch only if the JSON you send contains that "patterns" section. To use one from a script:

  1. On this page, click Hatches…, add your hatch (the three steps in that window), and close the window.
  2. Click Format. The JSON editor now has a "patterns" section at the end. For example, a hatch with the code FILL looks like this, with the SVG cut short here:
    "patterns": {
      "FILL": {
        "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\"><path fill=\"rgb(0,0,0)\" d=\"M 12 4 L 20 4 …\"/></svg>",
        "name": "Fill"
      }
    },
  3. Copy the JSON: click in the editor, press Ctrl+A (⌘+A on a Mac) to select all of it, then Ctrl+C to copy. Selecting all is easier than picking out the "patterns" section, because the "svg" or "image" line can be long.
  4. Paste it into a new text file and save it, for example as hatches.json.
  5. In the JSON your script sends, add the "patterns" section from that file, and set "hatch": "FILL" on each layer that should use it. For a sampler symbol, set a sample's "type" to its code instead. A code that replaces a built-in one, such as SM, needs no "hatch": every layer with that USCS symbol uses it.

A script can read the saved file and add its hatches to every log it sends:

import json, requests

hatches = json.load(open("hatches.json"))["patterns"]   # the JSON copied from this page

log = json.load(open("boring.json"))
log["patterns"] = hatches
log["layers"][0]["hatch"] = "FILL"                      # the layers that use the hatch

r = requests.post("https://uclageo.com/boring-log-viewer/api/render",
                  params={"format": "svg"}, json=log)
r.raise_for_status()
open("boring.svg", "w", encoding="utf-8").write(r.text)

You can also write a simple hatch by hand. This one draws diagonal lines, one tile 40 × 20 px (the tile's size comes from its viewBox); single quotes inside the SVG save escaping them in JSON:

"patterns": {
  "SLOPE": {
    "name": "Sloping lines",
    "svg": "<svg viewBox='0 0 40 20'><line x1='0' y1='20' x2='40' y2='0' stroke='black' stroke-width='1.5'/></svg>"
  }
}

Only drawing elements (path, rect, circle, ellipse, line, polyline, polygon, g) and fill and stroke attributes are kept; titles and editor metadata (from Inkscape or Illustrator) are dropped, and anything else, such as text, embedded images, <style> or scripts, is rejected with a message saying what to change.

If a layer uses a code that isn't defined in "patterns", the API returns a 422 error naming the layer and the code. To reuse a hatch in another log on this page, paste the "patterns" section into that log's JSON, or add the image again with the Hatches… window.