JavaScript in your own page
The viewer's drawing code is plain JavaScript. Use it in your own web page or Node.js program to draw boring logs with no server and nothing sent anywhere.
This is the third way to draw a log, next to the web page and the render API. It suits a website that shows its own borings, an offline tool, or a program that draws many logs.
The main function is renderBoringLog(log, options). It takes a boring log (a JSON object, or JSON text, as in the data format reference) and the display options, and returns the drawing as SVG text. Put the SVG in the page, or save it as a file.
The shortest example
Save this as boring-log.html and open it in a browser. The code is loaded from the GitHub repository through the jsDelivr CDN, so there is nothing to install.
boring-log.html<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Boring log</title></head>
<body>
<div id="log"></div>
<script type="module">
import { renderBoringLog } from 'https://cdn.jsdelivr.net/gh/sjbrandenberg/boring-log-viewer@main/src/render.js';
const log = {
units: { length: "ft" },
metadata: { boring_name: "B-1" },
layers: [
{ top: 0, bottom: 4, description: "Brown, loose, moist, silty SAND (fill)" },
{ top: 4, bottom: 20, description: "Gray, soft, wet, lean CLAY" }
],
samples: [{ top: 7.5, bottom: 9, name: "S-1", type: "SPT", blows: [3, 4, 4] }]
};
document.getElementById('log').innerHTML = renderBoringLog(log, { width: 800 });
</script>
</body>
</html>If your browser won't run it from a file on your disk, serve the folder instead: run python -m http.server in it and open http://localhost:8000/boring-log.html.
A small application
This page is a working application in about 100 lines. You can type or paste JSON, or open JSON, Excel, AGS4 and DIGGS files (several at once), and each boring is drawn. You can also switch between metric and US units and download the logs as SVG files. Download it and open it in a browser to try it, then change it to suit your own site.
boring-log-app.htmlDownload<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>My boring log app</title>
<style>
body { font-family: system-ui, sans-serif; margin: 16px; color: #222; }
.bar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-bottom: 8px; }
textarea { width: 100%; height: 220px; font: 13px monospace; box-sizing: border-box; }
#message { color: #b00020; white-space: pre-wrap; }
#logs svg { display: block; max-width: 100%; height: auto; margin: 12px 0; border: 1px solid #ddd; }
</style>
</head>
<body>
<h1>My boring log app</h1>
<div class="bar">
<label>Open JSON, Excel, AGS4 or DIGGS files <input id="files" type="file" multiple accept=".json,.xlsx,.ags,.xml"></label>
</div>
<textarea id="json" spellcheck="false">{
"units": { "length": "ft" },
"metadata": { "boring_name": "B-1" },
"layers": [
{ "top": 0, "bottom": 4, "description": "Brown, loose, moist, silty SAND (fill)" },
{ "top": 4, "bottom": 12, "description": "Gray, medium dense, wet, poorly graded SAND with silt" },
{ "top": 12, "bottom": 20, "description": "Gray, soft, wet, lean CLAY" }
],
"samples": [
{ "top": 7.5, "bottom": 9, "name": "S-1", "type": "SPT", "blows": [6, 9, 11] },
{ "top": 12.5, "bottom": 14.5, "name": "T-2", "type": "Shelby", "recovery_percent": 90,
"specimens": [{ "name": "T-2a", "top": 12.6, "bottom": 13.1, "water_content": 36.5, "liquid_limit": 44, "plastic_limit": 21, "uscs": "CL" }] }
]
}</textarea>
<div class="bar">
<button id="draw">Draw</button>
<label>Units <select id="units"><option value="">as in the data</option><option value="m">metric</option><option value="ft">US</option></select></label>
<button id="download" disabled>Download SVG</button>
</div>
<p id="message"></p>
<div id="logs"></div>
<script type="module">
// The viewer's code, loaded straight from GitHub. Replace "main" with a release
// tag or commit to pin a version, or download the src folder and use a local
// path such as './boring-log-viewer/src/'.
const LIB = 'https://cdn.jsdelivr.net/gh/sjbrandenberg/boring-log-viewer@main/src/';
const { renderBoringLog } = await import(LIB + 'render.js');
const { xlsxToBoringLog } = await import(LIB + 'xlsx.js');
const { agsToBoringLogs } = await import(LIB + 'ags.js');
const { diggsToBoringLogs } = await import(LIB + 'diggs.js');
const $ = id => document.getElementById(id);
let drawn = []; // [{ name, svg }]
// Draws a list of boring logs (JSON objects) into the page.
function draw(logs) {
$('message').textContent = '';
$('logs').innerHTML = '';
drawn = [];
for (const log of logs) {
const name = log.metadata?.boring_name ?? 'boring-log';
try {
const svg = renderBoringLog(log, { width: 900, units: $('units').value || undefined });
$('logs').insertAdjacentHTML('beforeend', svg);
drawn.push({ name, svg });
} catch (e) {
// A log that can't be drawn: e.issues lists each problem with its JSON path.
const issues = (e.issues ?? []).map(i => ` ${i.path}: ${i.message}`).join('\n');
$('message').textContent += `${name}: ${e.message}\n${issues}\n`;
}
}
$('download').disabled = drawn.length === 0;
}
$('draw').onclick = () => {
try {
draw([JSON.parse($('json').value)]);
} catch (e) {
$('message').textContent = `Not valid JSON: ${e.message}`;
}
};
$('units').onchange = () => $('draw').click();
// Every file opened becomes one or more logs (an AGS4 or DIGGS file has one per borehole;
// boreholes without strata, such as CPT locations, are skipped).
const withStrata = converted => converted.documents.map(d => d.document).filter(doc => doc.layers.length > 0);
$('files').onchange = async e => {
const logs = [];
for (const file of e.target.files) {
try {
if (/\.xlsx$/i.test(file.name)) {
logs.push((await xlsxToBoringLog(await file.arrayBuffer())).document);
} else if (/\.ags$/i.test(file.name)) {
logs.push(...withStrata(agsToBoringLogs(await file.text())));
} else if (/\.xml$/i.test(file.name)) {
logs.push(...withStrata(diggsToBoringLogs(await file.text())));
} else {
logs.push(JSON.parse(await file.text()));
}
} catch (err) {
$('message').textContent += `${file.name}: ${err.message}\n`;
}
}
if (logs.length === 1) $('json').value = JSON.stringify(logs[0], null, 2);
draw(logs);
};
$('download').onclick = () => {
for (const { name, svg } of drawn) {
const a = document.createElement('a');
a.href = URL.createObjectURL(new Blob([svg], { type: 'image/svg+xml' }));
a.download = `${name}.svg`;
a.click();
URL.revokeObjectURL(a.href);
}
};
$('draw').click();
</script>
</body>
</html>The parts it uses, all in the repository's src folder, and none needing anything else:
| Module | Function | What it does |
|---|---|---|
render.js | renderBoringLog(log, options) | Draws a log and returns the SVG text. If the log can't be drawn, it throws an error whose issues list each problem with its JSON path (/layers/0) and message. |
xlsx.js | await xlsxToBoringLog(bytes) | Reads an Excel workbook laid out like the template. Returns { document, warnings }. |
ags.js | agsToBoringLogs(text) | Converts an AGS4 file. Returns { documents: [{ loca_id, document }], warnings }, one per borehole. |
diggs.js | diggsToBoringLogs(text) | Converts a DIGGS file, in the same form as agsToBoringLogs. |
@main in the address loads the latest code, which can change. For a website that should keep drawing the same way, replace main with a release tag or a commit. Or download the repository's src folder, put it next to your page, and import from it, e.g. './boring-log-viewer/src/render.js'.
Checking a log
renderBoringLog stops only on problems that make a log impossible to draw. A full check against the JSON Schema (for example, misspelled field names, and warnings such as gaps between layers) is validateBoringLog(log). It needs the Ajv library, so in a browser either use a bundler (below) or send the log to the API's api/validate. It returns { valid, errors, warnings }.
In Node.js or with a bundler
Install the package from GitHub, then import from it:
npm install github:sjbrandenberg/boring-log-viewer
import { readFileSync, writeFileSync } from 'node:fs';
import { renderBoringLog, validateBoringLog } from 'boring-log-viewer';
const log = JSON.parse(readFileSync('B-1.json', 'utf8'));
const { valid, errors, warnings } = validateBoringLog(log);
if (!valid) throw new Error(JSON.stringify(errors, null, 2));
for (const w of warnings) console.warn(w.path, w.message);
writeFileSync('B-1.svg', renderBoringLog(log, { width: 900, units: 'ft' }));
This needs Node.js 22 or later. To make a PNG, convert the SVG with a library such as @resvg/resvg-js, as the API does. The same import works in a web application built with Vite, webpack or esbuild, which also bundles Ajv for validateBoringLog.