wearcheck 0.1.0

CLI tool for estimating and visualising mechanical wear

Wearcheck: tribological wear resistance estimator

Created for "Knowera" by Dmytro Tkachivskyi, PhD

Table of contents

• Short description
• Screenshots
• Elaborate description
• Features
  • Assumptions
• Prerequsites
  • Getting FreeCAD
• Wearcheck package installation
  • For users (non-editable)
  • For contributors (editable)
• Adding your own data
  • Adding new material
  • Adding new erodent
    • Determining erodent aggressiveness factor
• Inspiration
• Licensing
• Support this project

Short description

Wearcheck is a zero‐hassle cross-platform CLI (command line interface) tribological utility for quick abrasive or erosive mechanical wear‐risk estimates on CAD parts. A conjunction of Archard's equation (modified for erosion and 3-body sliding or abrasion wheel cases), β-curve distribution function and FreeCAD software is used for accurate wear prediction.

Screenshots

Image 1. Determining erosion of AISI 316L steel in terminal under 42° impact angle, using theoretical β-distribution curve

Image 2. Visualising sliding abrasive wear of Hardox 400 steel in 3D

Image 3. Visualising aribitrary heat map during erosive wear of TiC-NiMo + AISI 316L cermet in 3D

Image 4. Theoretical erosive wear and heat map of ICE's parts with complex geometry. (It would be impossible to check them for the given conditions in real life)

Elaborate description

Wearcheck is a single-command “what-if” calculator for mech­anical wear of part of any geometrical complexity. It is aimed at engineers who need a first-order answer now, long before a full DOE or dozens of ASTM/GOST (and other standards) coupons can be scheduled.

Use Wearcheck when you do care about wear, but don’t have the calendar, budget or lab capacity to test every permutation:

• One command in terminal gives almost instant answer: the script converts the STEP to a mesh, shoots rays to find exposed facets, applies an angle-weighted Archard/β-model, and prints:
  • predicted volume loss & risk tier;
  • a plain-text angular wear curve (abrasion or erosion);
  • an optional colour map on the real geometry.
• Explore the full design space: vary load, speed, particle flow, material, impact angle without cutting a single extra coupon.
• Bridge data gaps: when only two reference points (30 ° and 90 ° empirical AEW/ARWW) exist, Wearcheck fits a smooth β-distribution so you still see the whole curve.
• No heavyweight CAE or GUI: everything is CLI-friendly and runs on commodity hardware; FreeCAD is only called in head-less mode.
• Fully portable: install from PyPI (pip install wearcheck) or just drop the pre-built wearcheck.pyz on any machine with Python ≥ 3.9.

Features

Flag / Argument	What it means	Default / Notes
Positional STEP / STL / OBJ	The 3-D part to analyse. Omit it and the bundled 25 × 50 × 10 mm coupon is used.
--mat, --material	Material under test   (key in materials.json)	mandatory
--wt, --wear-type	Mechanism: abrasion (3-body sliding) or erosion (particle impact)	abrasion
--impact X Y Z / --angle °	Attack direction - either a full 3-D vector (--impact) for real parts or a simple polar angle (--angle) for flat coupons.	required for erosion
--med, --medium	Abrasive / erodent name  (key in erodents.json)	Silica_Sand
--load	Normal load W (N) – abrasion only	130 N
--velocity, --vel	Particle or belt speed v (m · s⁻¹)	v_ref from erodent DB
--feed-rate, --fr	Mass flow rate ṁ (g · s⁻¹)	mandatory
--time, --t	Exposure duration t (s)	mandatory
--visualize, --vis	Show a PyVista 3-D scene with risk map, scalar bar, hot/cold toggle, grid & camera shortcuts.	off
--interactive, --int	Prompt for calibration of custom LOW / MEDIUM / HIGH risk thresholds.	off
Keyboard hot-keys in viewer	G grid, M wear ⇄ heat, I screenshot, 1–9 preset views.

Assumptions

• Erosive mode
  --angle ( -a ) or --impact x y z (--imp x y z) describe only the polar angle θ between the abrasive jet and the horizontal plane. The auxiliary angles β and δ, and particles flying distance defined in the standard (e.g., GOST 23.201-78) are already absorbed into the fitted Archard/β coefficients; you do not enter them separately.

• Abrasive (sliding) mode
  The mechanical wear volume predicted by the 3-body Archard equation is mapped as a uniform thinning over the test surface. In real ASTM G65 tests the scar is oval-shaped and centred; the visual map therefore differs, but the total wear (mm³) and the wear rate (mm³/N·m) are calibrated to match reference coupon results as closely as possible.

• Coated parts (HVOF spraying, cladding, etc.)
  When your material is a coating on a substrate (not a solid block like Hardox 400), the predicted wear depth refers to how much of that coating layer is removed. Always compare the script’s estimated wear height on the test surface to your known coating thickness — if the wear depth exceeds the layer thickness, the substrate would be exposed in a real test.

Prerequsites

• Python ≥ 3.9 (to check run "python3 --version");
• FreeCAD ≥ 0.21 (its command‐line binary "freecadcmd" must be on machine's PATH).

Getting FreeCAD

• on Windows: install the normal FreeCAD desktop package (e.g., FreeCAD-x.y.z-Win-x64.exe), and tick “Add FreeCAD to PATH” during installation;
• on Linux (Debian-based): install standard distro package (e.g., run command "sudo apt install freecad");
• on MacOS: install official .dmg package (e.g., run command "brew install FreeCAD").

Wearcheck package installation

For users (non-editable)

• Get from PyPI registry:

python3 -m pip install wearcheck # download and install package
wearcheck --mat "Hardox 400" ... # run with standard 25x50x10 mm step part
wearcheck "/path/to/part.step" --mat "Hardox 400" ... # run with any custom part on the system
wearcheck --help # call help

• Download single zipapp file:

wget -O wearcheck.pyz \
https://github.com/dmtkac/knowera-wearcheck/releases/latest/download/wearcheck.pyz # download package via terminal
chmod +x wearcheck.pyz # grant executable rights
./wearcheck.pyz --mat "Hardox 400" ... # run with standard 25x50x10 mm step part
./wearcheck.pyz "/path/to/part.step" --mat "Hardox 400" ... # run with any custom part on the system
./wearcheck.pyz --help # call help

For contributors (editable)

git clone https://github.com/dmtkac/knowera-wearcheck

# first time use
cd ~/path/to/the/cloned/repo
# create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate
# install dependencies
pip install -e .

# subsequent usage
cd ~/path/to/the/cloned/repo
source .venv/bin/activate

# syntax examples
wearcheck --mat "Hardox 400" ... # run with standard 25x50x10 mm step part
wearcheck "/path/to/part.step" --mat "TiC-NiMo + AISI 316L" ... # run with any custom part on the system

# call help
wearcheck --help

# exit virtual environment
deactivate

Adding your own data

Adding new material (materials.json)

Fill 7 keys per material: hardness_MPa, wear_k, e30, e90, beta_a, beta_b; (optionally keep hardness_HV or hardness_HBW for reference).

Step	What you measure / calculate	JSON field(s) you fill
1. Hardness	Any scale is OK (HV, HBW, GPa)  → convert to MPa: MPa = HV × 9.807   or   MPa = HBW × 9.807	"hardness_MPa": … (optionally, keep the raw number, e.g. "hardness_HV": …)
2. Abrasion coupon (ASTM G65)	Measure coupon volume loss Q_exp (mm³). Note load W [N], sliding distance L [m], abrasive mass M [kg].
3. Archard 3-body factor	wear_k = (Q_exp · H_MPa) / (W · L · M)	"wear_k": …
4. Erosion coupons	Air-jet / slurry tests on flat coupons at 30 ° and 90 °. Record AEW (mm³ / kg).	"e30": … "e90": …
5. β-curve shape	Tweak beta_a > 1, beta_b > 1 until the theoretical curve crosses your e30 & e90 points smoothly. (Use e30 = e90 = 1 temporarily while tuning.)	"beta_a": … "beta_b": …
6. Insert block	e.g., Cr3C2-Ni

"Cr3C2-Ni": {
  "hardness_HV": 1270,
  "hardness_MPa": 12446,
  "wear_k": 41.61e5,
  "e30": 8.956e7,
  "e90": 13.89e7,
  "beta_a": 1.2,
  "beta_b": 1
}

Verify

wearcheck "Cr3C2-Ni" --wt erosion   --med "Silica Sand"  --a 42   --vel 40   --fr 2.5   --t 2400
wearcheck "Cr3C2-Ni" --wt abrasion   --med "Silica Sand"  --vel 2.4   --fr 6.17   --t 300

Adding new erodent (erodents.json)

Each abrasive / erodent entry needs only two values:

Key	Meaning	Example
factor	Relative aggressiveness (dimensionless). 1.0 is the baseline “Silica Sand”. Wear volume predicted by the model is multiplied by this factor.	Silica Sand → 1.00 White Alumina → 1.73
v_ref	Reference particle speed (m · s⁻¹) at which your empirical e30/e90 were measured. The code scales wear with ((v / v_{ref})^{n}) where n defaults to 2 or is given per material.	40.0 m/s

Determining erodent aggressiveness factor

1. Run the same coupon test (30 ° or 90 °) with the baseline sand and with your new abrasive;
2. Compute the ratio of volume-loss per kilogram: factor = AEW_alumina_30/AEW_silica_30 (or AEW_alumina_90/AEW_silica_90);
3. Round to two decimals and enter as "factor";
4. Add to erodents.json:

{
  "Silica Sand"  : { "factor": 1.00, "v_ref": 40.0 },
  "Alumina Wheel": { "factor": 1.73, "v_ref": 60.0 },
  ...
}

How was the Alumina factor determined (1.73)?

Once Cr3C2–Ni entered the materials library in materials.json, it became possible to run wear predictions under identical β-curve calibration for both Silica Sand and an Alumina Wheel at the speed used in AEW dataset (in this case 60 m/s) over the 30°–90° range (in this case only AEW_30 and AEW_90 were used). Comparing silica-simulated wear rate to published AEW data, which used alumina wheel, revealed that Cr3C2–Ni lost about 73% more volume per kilogram with alumina than with silica under the same conditions. That directly yields the 1.73 aggressiveness factor for the Alumina Wheel entry.

Verify

wearcheck "Hardox 400" --wt abrasion --med "Alumina Wheel" --vel 3.2 --fr 4.5 --t 600 
wearcheck "TiC-NiMo + AISI 316L" --wt abrasion --med "Alumina Wheel" --vel 2.4 --fr 6.0 --t 300

Inspiration

This tool grew out of my doctoral research on sliding and impact wear of HVOF-sprayed hardmetal/steel composites. Most of the materials database (Hardox 400, AISI 316L, TiC-NiMo + 316L) comes directly from my own coupon work-ups. An additional entries (material Cr3C2-Ni and erodent Alumina Wheel) were incroprated from my colleagues' research (I. Hussainova et al., 2007) to show that the same β-curve/Archard framework adapts to any "material + medium" pair once two calibration points are known.

Wearcheck is therefore both:

• a personal lab notebook distilled to code, and
• a generic template other researchers can extend with their own materials.json rows and erodent descriptions.

If this utility helps you save machine time or sparks ideas for your own experiments, please cite it — or better, contribute your data back to the library or codebase, so it keeps growing, enriching FOSS ecosystem.

Licensing

This work is licensed under the MIT License.

Support this project

If you enjoyed this project or found it useful, consider supporting me! Your donations help me to maintain and develop future improvements.