Boring Log Viewer docs

This whole page is new.

Excel workbooks

Fill in a workbook in Excel and open it in the viewer: it is turned into the boring log JSON and drawn, with no JSON to write.

Download the Excel template  Download a filled-in example

The example is boring B-3, the coastal example of the viewer's Load example… list: six layers, eight samples (SPT, Shelby tube, Modified California and bulk), lab specimens with water content, unit weights, fines and Atterberg limits (one non-plastic), and a groundwater reading, all in metric units. Open it in Excel to see how each sheet is filled in, then open it in the viewer to see the log it gives. A second example, NAS-1.xlsx, is a real boring from Nantou, Taiwan. The Excel template and Excel example buttons on the viewer page give the same files.

How to use it

  1. Download the template. It has a README sheet and one sheet for each part of the log: Units, Metadata, Layers, Samples, Specimens, Groundwater, Depth notes, References, Layout and Columns.
  2. Fill in the sheets you need. Only Layers is needed for a log; leave the others empty or delete them.
  3. Save it as an Excel Workbook (.xlsx). On the viewer page, click Open files… (or drag the workbook onto the text box).
  4. The workbook opens as one log, in its own tab, named after its boring_name. The converted JSON appears in the text box and the log is drawn. A note above the text box lists anything that couldn't be read, with the sheet and cell, such as Layers!B7 (top): "x" is not a number.

The workbook is read in your browser and isn't uploaded. Once it is open, it is a log like any other: edit the JSON, use Layout… and Hatches…, and download it. The workbook itself isn't changed, so if you edit the JSON, download it or keep editing the workbook and open it again.

One workbook holds one boring. For several borings, make one workbook each and open them all at once; each gets its own tab (see Several logs and the map).

How a sheet is laid out

There are two kinds of sheet:

The explanations are optional

You can delete the title and explanation rows, the explanation column and the README sheet; the workbook is read the same way. The viewer finds a table's header row by its field names (on the Layers sheet, the first row with both top and bottom), wherever it is, and reads a field/value sheet wherever a field name has a value to its right. Rows above the header are ignored.

What the viewer is flexible about:

Units

Every depth, thickness and elevation is in the length unit on the Units sheet (m or ft), unit weights in kN/m3 or pcf, and diameters in mm, cm, m, in or ft. Left empty, the units are m, kN/m3 and mm. Type numbers only (1.5, not 1.5 m); a unit in brackets in a header is fine, but it is only a label: the Units sheet decides.

Samples and specimens

Laboratory results belong to specimens, and specimens to samples (see Samples, specimens and tests). On the Specimens sheet, put the sample's name (as on the Samples sheet) in the sample_name column. If it is empty, the specimen goes to the sample whose depths contain the specimen's top. A specimen that matches no sample is left out, with a note.

Your own columns

To show values the log has no column for, such as pocket penetrometer readings or undrained strength:

  1. Add a column to the Samples (or Specimens) sheet, with a header made of letters, digits and _, such as cu. Its values become each sample's custom values.
  2. On the Columns sheet, list the columns of the log in order, including a row with id cu, source sample and a label such as Su (kPa). Leave the Columns sheet empty to keep the built-in columns (your own then aren't shown).

See Columns and layout for the column ids and widths. Custom hatches and sampler symbols aren't part of the workbook: add them with Hatches… after opening it.

The sheets and their fields

The field names are the ones in the JSON (see the data format reference).

Units

The units every number in the workbook is given in. Leave a value empty for the default (shown first). Field/value sheet; becomes units in the JSON.

Field (column A)TypeWhat goes in it
lengthchoiceDepths, thicknesses and elevation: m or ft. Default m.
unit_weightchoiceUnit weights: kN/m3 or pcf. Default kN/m3.
diameterchoiceBorehole and sampler diameters: mm, cm, m, in or ft. Default mm.

Metadata

The boring itself: shown in the heading of the log. Every value is optional. Field/value sheet; becomes metadata in the JSON.

Field (column A)TypeWhat goes in it
boring_nametextName of the boring, e.g. B-1. Also used for the file names of downloads.
projecttextProject name.
site_nametextSite name or address.
latitudenumberDecimal degrees, WGS84 (e.g. 34.0689). Places the boring on the map.
longitudenumberDecimal degrees, WGS84; negative west of Greenwich (e.g. -118.4452).
elevationnumberGround surface elevation, in the length unit chosen on the Units sheet (m or ft).
datumtextElevation datum, e.g. NAVD88.
start_datedateDate drilling started. An Excel date or text such as 2024-05-01.
end_datedateDate drilling ended.
boring_typetextDrilling method, e.g. hollow-stem auger, mud rotary.
rigtextDrill rig.
diameternumberBorehole diameter, in the diameter unit chosen on the Units sheet (mm, cm, m, in or ft).
hammertextHammer type, e.g. automatic trip, 140 lb.
energy_rationumberHammer energy ratio, percent (e.g. 80).
logged_bytextWho logged the boring.
drillertextDrilling contractor or driller.
notestextAny other notes, shown in the heading.

Layers

One row per stratigraphic layer, from the top down. At least one layer is needed to draw a log. Table sheet: one row each; becomes layers[] in the JSON.

Column headerTypeWhat goes in it
top (required)numberDepth to the top of the layer, in the length unit chosen on the Units sheet (m or ft). Required.
bottom (required)numberDepth to the bottom of the layer, in the length unit chosen on the Units sheet (m or ft). Required.
descriptiontextSoil or rock description, as it should appear on the log.
uscstextUSCS group symbol, e.g. SM, a dual symbol such as SP-SM, or a borderline symbol such as CL/ML.
hatchtextGraphic log pattern if different from the USCS symbol, e.g. FILL, SANDSTONE. Leave empty to draw the USCS pattern.

Samples

One row per sample. Lab test results go on the Specimens sheet. Any extra column you add (e.g. cu) is kept as a custom value of the sample; show it with the Columns sheet. Table sheet: one row each; becomes samples[] in the JSON.

Column headerTypeWhat goes in it
nametextSample name or number, e.g. S-1. Specimens are linked to their sample by this name.
top (required)numberDepth to the top of the sample, in the length unit chosen on the Units sheet (m or ft). Required.
bottom (required)numberDepth to the bottom of the sample, in the length unit chosen on the Units sheet (m or ft). Required.
typetextSampler type: SPT, ModCal, DamesMoore, Shelby, Piston, Osterberg, Pitcher, Denison, LargeDiameter, Block, DirectPush, GelPush, Sonic, Core, TripleTube, Bulk, Grab, Composite, Auger, Trench, Disturbed, Other. Empty means Other.
uscstextUSCS symbol of the sample, if classified separately from the layer.
sampler_diameternumberSampler outer diameter, in the diameter unit chosen on the Units sheet (mm, cm, m, in or ft).
recovery_percentnumberRecovery, percent of the sample length (top to bottom); 0 means no recovery.
blow_countnumber or textBlow count as reported (N or blows/ft), e.g. 23, or text such as 50/3in for refusal.
blowsnumbers, comma separatedBlows per increment, separated by commas, e.g. 6, 8, 10.
energy_rationumberHammer energy ratio for this sample, percent. Overrides the one on the Metadata sheet.
total_unit_weightnumberTotal unit weight of the whole sample (e.g. a tube weighed before extrusion), in the unit weight unit chosen on the Units sheet (kN/m3 or pcf). Results on specimens go on the Specimens sheet.
dry_unit_weightnumberDry unit weight of the whole sample, in the unit weight unit chosen on the Units sheet (kN/m3 or pcf).
remarkstextSample remarks, shown in the remarks column.

Specimens

One row per laboratory specimen. Each belongs to a sample: give the sample's name in sample_name (or leave it empty and the specimen goes to the sample whose depths contain its top). Extra columns are kept as custom values of the specimen. Table sheet: one row each; becomes samples[].specimens[] in the JSON.

Column headerTypeWhat goes in it
sample_nametextName of the sample (Samples sheet) the specimen was cut from.
nametextSpecimen name within the sample, e.g. 1 or A.
topnumberDepth to the top of the specimen, in the length unit chosen on the Units sheet (m or ft). Empty: the sample's depths are used.
bottomnumberDepth to the bottom of the specimen, in the length unit chosen on the Units sheet (m or ft).
water_contentnumberNatural water content, percent.
total_unit_weightnumberTotal (bulk) unit weight, in the unit weight unit chosen on the Units sheet (kN/m3 or pcf).
dry_unit_weightnumberDry unit weight, in the unit weight unit chosen on the Units sheet (kN/m3 or pcf).
specific_gravitynumberSpecific gravity of solids, e.g. 2.65.
fines_contentnumberPercent passing the No. 200 sieve.
liquid_limitnumberLiquid limit, percent.
plastic_limitnumberPlastic limit, percent.
nonplasticTRUE / FALSETRUE (or yes, NP) if the specimen is non-plastic; LL and PL are then ignored.
uscstextUSCS symbol from the laboratory classification of the specimen, e.g. CL. Shown in the Lab USCS column.
remarkstextSpecimen remarks.

Groundwater

One row per groundwater reading. Table sheet: one row each; becomes groundwater[] in the JSON.

Column headerTypeWhat goes in it
depth (required)numberDepth to water, in the length unit chosen on the Units sheet (m or ft). Required.
datedateDate of the reading. An Excel date or text.
notetextE.g. encountered during drilling, stabilized.

Depth notes

Observations at a single depth within a layer, e.g. "trace gravel" or "becomes wet". Drawn as a tick in the description column. Table sheet: one row each; becomes depth_notes[] in the JSON.

Column headerTypeWhat goes in it
depth (required)numberDepth of the observation, in the length unit chosen on the Units sheet (m or ft). Required.
description (required)textThe observation. Required.

References

Sources of the data, e.g. the report the boring comes from. Listed under the log. Table sheet: one row each; becomes references[] in the JSON.

Column headerTypeWhat goes in it
text (required)textThe reference, e.g. author, year, title. Required.
urltextLink to the source (optional).

Layout

Size of the log. Leave empty to use the viewer's settings. The columns themselves go on the Columns sheet. Field/value sheet; becomes layout (width, font_size) in the JSON.

Field (column A)TypeWhat goes in it
widthnumberWidth of the log in px, 300 to 4000 (e.g. 900).
font_sizenumberFont size in px, 6 to 24 (e.g. 10).

Columns

Which columns the log shows, in order (left to right). Leave the sheet empty for the built-in columns. depth, graphic and description are always drawn. Table sheet: one row each; becomes layout.columns[] in the JSON.

Column headerTypeWhat goes in it
id (required)textColumn id: depth, elevation, groundwater, graphic, uscs, description, sample_type, sample_name, sampler_diameter, blow_count, energy_ratio, specimen, specimen_name, water_content, total_unit_weight, dry_unit_weight, specific_gravity, fines_content, liquid_limit, plastic_limit, specimen_uscs, remarks; or a new id for your own column.
widthnumberRelative width, e.g. 1 for a narrow column and 8 for the description. Empty: the default.
labeltextColumn heading. Empty: the built-in heading, or the id.
sourcechoiceYour own columns only: sample (a column of the Samples sheet), specimen (of the Specimens sheet) or blank (an empty column).
fieldtextYour own columns only: the header of that extra column on the Samples or Specimens sheet. Empty: the same as id.
decimalswhole numberYour own columns only: decimals shown for numbers, 0 to 6.

If something is missing

Check the note above the text box: it names the sheet, row or cell of each value that was left out and why. Old .xls workbooks can't be read; open them in Excel and save them as Excel Workbook (.xlsx). A workbook saved by LibreOffice, Numbers or Google Sheets as .xlsx works too.