Getting started
Reference the libraries
Reference the projects you need; the data and loader libraries have no UI dependency and run in services.
| You want to | Reference |
|---|---|
| Read files / databases into the canonical model | TheTechIdea.OilGas.Wellbore.Data, TheTechIdea.OilGas.Wellbore.Loaders |
| Draw logs | + TheTechIdea.OilGas.Wellbore, TheTechIdea.OilGas.WellLogs |
| Draw schematics, barriers, integrity views | + TheTechIdea.OilGas.Wellbore, TheTechIdea.OilGas.WellSchematic |
Target frameworks: .NET 8 and .NET 9. Drawing uses SkiaSharp 4 (paths are built through SKPathBuilder only).
Your first view
// Application start-up: load the customer's environment once (in an app: WellboreServices.Global = ...).
// Here it is scoped by the caller; see the multi-tenant scenario.
// 1. Load a well through a mapping profile (the environment's profile folder is searched first).
var provider = new MappedWellDataProvider(new CsvTabularSource(csvFolder), MappingProfile.Load("csv"));
WellLoadResult result = await provider.LoadWellAsync("CSV-1");
foreach (var warning in result.Warnings) Console.WriteLine("data: " + warning);
// 2. Build the view: schematic + tally + logs / pressure / core tracks from the log family.
var view = WellModelConverter.ToWellboreView(result.Model,
new WellModelConversionOptions { ExtraTracks = WellLogTracks.FromModel, GenerateBarriers = true }, out var conversionWarnings);
// 3. Host it: WellboreView draws on any SkiaSharp canvas; wire it to your UI control (see README): zoom, pan, cursor, selection, top dragging.
var canvas = new WellboreView { Document = view, Width = 1600, Height = 1000 };
canvas.View.SetRange(view.Axis, 9000, 12000); // zoom to the completion
canvas.MarkerMoved += (s, move) => Console.WriteLine($"{move.Marker.Name} moved to {move.To}");
// 4. Check the data before showing it, then export what the user sees (ToPdf, ToSvg or ToPng).
IReadOnlyList<WellboreIssue> issues = canvas.Validate();
using var pdf = new MemoryStream();
int pages = WellboreExport.ToPdf(view, pdf);
WellModelConverter.ToWellboreView builds a depth track, the schematic, the tally and - through ExtraTracks - any
family's tracks (here logs, pressure and core data from WellLogTracks.FromModel). WellboreView is host-independent:
it draws on any SkiaSharp canvas. Your UI control wires Invalidated to its redraw and forwards pointer and wheel input
(HandleMouseDown/Move/Up/Hover/Wheel/Leave); the view then zooms, pans, shows the depth cursor, selects items and lets
interpreters drag tops. The repository README shows the ten-line wiring for WinForms, WPF, MAUI or Avalonia controls.
Next steps
The Tutorials build a first view, a custom track, a company environment and a live feed step by step.
Samples
samples/HeadlessReport (runs anywhere: environment, loading, validation gate, PDF / SVG / PNG) and samples/WinFormsViewer
(Windows: a WellboreView in a SkiaSharp SKControl with mouse, wheel, menus and export) share one Workbench class with all
domain logic; the UI sample shows the few lines any SkiaSharp host needs. CI runs the headless sample on every build.
Give it the customer's environment
Create a JSON file with only the settings that differ from the defaults (the full list with defaults is
environment.template.json):
{
"name": "Acme Energy",
"units": { "depthUnit": "ft" },
"cement": { "goodBondIndex": 0.7 },
"resources": { "lexiconFiles": [ "company.lexicon.json" ], "mappingProfilesFolder": "profiles" }
}
Load it once at start-up, or per request in a server (see the multi-tenant scenario):
WellboreServices.Global = WellboreServices.Load("acme.environment.json");
foreach (var w in WellboreServices.Global.Warnings) log.Warn(w); // unknown keys, missing files, invalid values
Point your editor at environment.schema.json for completion and validation.
Run the tests
dotnet test tests/TheTechIdea.OilGas.Tests
The suite includes the scenario samples of this guide, parity tests proving the default environment reproduces the
built-in behaviour, and golden images (the first run writes them to tests/TheTechIdea.OilGas.Tests/Golden/pending/ for review).
Rebuild these docs
WELLBORE_DOCS_OUT=build/docs-data dotnet test tests/TheTechIdea.OilGas.Tests --filter DocumentationDumpTests
python3 tools/docs/build_docs.py --repo . --data build/docs-data --previews <folder of rendered previews>
The generator fails on unresolved placeholders, broken links or missing images.