diff --git a/README.md b/README.md index ca8506a..e989531 100644 --- a/README.md +++ b/README.md @@ -1,86 +1,79 @@ -## A Gear module for FreeCAD -[![Liberapay](http://img.shields.io/liberapay/patrons/looooo.svg?logo=liberapay)](https://liberapay.com/looooo/donate) +# FreeCAD Gears + +A gear workbench for FreeCAD: create involute, cycloid, bevel, worm, timing, lantern and crown gears with full control over parameters. ## Requirements -FreeCAD > v0.16 -__python > 3 (for python2 use branch py2)__ -### Python packages -scipy, numpy, sympy (optional), jupyter (optional) +- **FreeCAD** ≥ 1.0 (or ≥ 0.16 for older setups) +- **Python** ≥ 3.8 (used by FreeCAD) +- **Python packages:** `numpy`, `scipy`, `sympy` (optional: `jupyter`, `matplotlib`) +## Supported gear types -## Supported gear-types - -### Cylindric Involute -* Shifting -* Helical -* Double Helical -* Undercut -* Fillets +### Cylindric involute +- Shifting, helical, double helical, undercut, fillets ![involute-gear](examples/images/involute-double-helical-gear.png) - -### Involute Rack +### Involute rack ![involute-rack](examples/images/involute-rack.png) -### Cylindric Cycloid -* Helical -* Double Helical -* Fillets +### Cylindric cycloid +- Helical, double helical, fillets ![cycloid-gear](examples/images/cycloid-gear.png) -### Cycloid Rack - +### Cycloid rack ![cycloid-rack](examples/images/cycloid-rack.png) -### Spherical Involute Bevel-Gear -* Spiral +### Spherical involute bevel gear +- Spiral ![bevel-gear](examples/images/bevel-gear.png) -### Crown-Gear +### Crown gear ![crown-gear](examples/images/crown-gear.png) -### Worm-Gear +### Worm gear ![worm-gear](examples/images/worm-gear.png) -### Timing-Gear +### Timing gear ![timing-gear](examples/images/timing-gear.png) -### Lantern-Gear +### Lantern gear ![lantern-gear](examples/images/lantern-gear.png) ---------------------------- +--- ## Installation -### Addon Manager -Starting from v0.17 it's possible to use the built-in FreeCAD [Addon Manager](https://github.com/FreeCAD/FreeCAD-addons#1-builtin-addon-manager) -located in the `Tools` > `Addon Manager` dropdown menu. +### Addon Manager (recommended) +In FreeCAD: **Tools** → **Addon Manager** → search for “Gears” (or “FCGear”) → Install. ### pip +```bash +pip install freecad.gears +``` +Or from source: +```bash +pip install https://github.com/looooo/freecad.gears/archive/master.tar.gz +``` +Use the same Python/pip that FreeCAD uses on your system. -`pip install https://github.com/looooo/FCGear/archive/master.tar.gz` - -**Important note:** Most systems have multiple versions of python installed. Make sure the `pip` you're using is used by FreeCAD as well. +--- ## Usage -### Create a gear manually -* Open freecad -* Switch to the gear workbench -* Create new document -* Create a gear (click on a gear symbol in the toolbar) -* Change the gear parameters - -## Scripted gears -Use the power of python to automate your gear modeling: +### In FreeCAD +1. Open FreeCAD and switch to the **Gear** workbench. +2. **File** → **New** (or open a document). +3. Create a gear from the toolbar and adjust parameters in the property panel. +### From Python ```python import FreeCAD as App import freecad.gears.commands + gear = freecad.gears.commands.CreateInvoluteGear.create() gear.num_teeth = 20 gear.beta = 20 @@ -90,21 +83,57 @@ App.ActiveDocument.recompute() Gui.SendMsgToActiveView("ViewFit") ``` -# Development: -if you have pixi installed just launch pixi and run this command -`pixi run freecad` to launch freecad with freecad.gears installed. +--- + +## Development + +The project uses [pixi](https://pixi.sh/) for environment and task management. + +### Setup +```bash +pixi install +``` + +### Pixi commands + + +### Tasks (Kurzreferenz) + +| Befehl | Beschreibung | +|--------|--------------| +| `pixi run freecad` | FreeCAD mit freecad.gears starten. | +| `pixi run lint` | Pylint. | +| `pixi run test` | Unit-Tests. | +| `pixi run test-visual` | Visual-Tests (Display nötig). | +| `pixi run test-visual-xvfb` | Visual-Tests unter xvfb. | +| `pixi run test-all` | Alle Tests. | +| `pixi run create-references` | Referenzbilder erzeugen. | +| `pixi run create-references-xvfb` | Referenzbilder unter xvfb. | +| `pixi run clean-test` | Test-Artefakte und Referenzen löschen. | + +Visual tests use [freecad.visual_tests](https://github.com/looooo/freecad.visual_tests): each project under `tests/data/*/` has a `metafile.yaml` and a `.FCStd` model; references are stored in `references/`. + +### CI (GitHub Actions) +- **Pylint:** Runs on push, pull_request and `workflow_dispatch` (lint does not fail the job). +- **Tests:** Unit tests on all OS; visual tests (xvfb) on Ubuntu only. +- **Update reference images:** Manual workflow “Update reference images” to regenerate references on CI and push them to the repo. + +--- ## References -* Elements of Metric Gear Technology ([PDF](http://qtcgears.com/tools/catalogs/PDF_Q420/Tech.pdf)) -### FreeCAD Forum threads -These are forum threads where FreeCAD Gears has been discussed. If you want to give Feedback -or report a bug please use the below threads. Please make sure that the report hasn't been reported already -by browsing this repositories [issue queue](https://github.com/looooo/freecad.gears/issues). -* "CONTINUED: involute gear generator preview !" ([thread](https://forum.freecadweb.org/viewtopic.php?f=10&t=4829)) -* "Bevel gear - module/script/tutorial" ([thread](https://forum.freecadweb.org/viewtopic.php?f=3&t=12878)) -* "Gears in FreeCAD: FC Gear" ([thread](https://forum.freecadweb.org/viewtopic.php?f=24&t=27381)) -* "FC Gears: Feedback thread" ([thread](https://forum.freecadweb.org/viewtopic.php?f=8&t=27626)) +- Elements of Metric Gear Technology ([PDF](http://qtcgears.com/tools/catalogs/PDF_Q420/Tech.pdf)) + +### FreeCAD Forum +- [Involute gear generator preview](https://forum.freecadweb.org/viewtopic.php?f=10&t=4829) +- [Bevel gear – module/script/tutorial](https://forum.freecadweb.org/viewtopic.php?f=3&t=12878) +- [Gears in FreeCAD: FC Gear](https://forum.freecadweb.org/viewtopic.php?f=24&t=27381) +- [FC Gears: Feedback thread](https://forum.freecadweb.org/viewtopic.php?f=8&t=27626) + +Please check the [issue tracker](https://github.com/looooo/freecad.gears/issues) before opening a new report. + +--- + +## License -# License GNU General Public License v3.0 diff --git a/pixi.lock b/pixi.lock index 0ecf5bb..5365c8e 100644 --- a/pixi.lock +++ b/pixi.lock @@ -4433,7 +4433,7 @@ packages: - pypi: ./ name: freecad-gears version: 1.3.0 - sha256: fc43346395605ed79fd151cd4120cd706c17ac3580f16a659f5be13967e0b572 + sha256: c829046851e9cbdd6b94cbb2074a91ef0193328b89a2e174148be2980fbf8eb3 requires_dist: - numpy - scipy diff --git a/pyproject.toml b/pyproject.toml index c38b6ea..93de5fb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,3 +28,6 @@ version = {attr = "pygears.__version__"} markers = [ "visual: visual regression tests (need display or xvfb)", ] +filterwarnings = [ + "ignore:builtin type.*__module__:DeprecationWarning", +] diff --git a/tests/data/projekt_001/involute_gear_test.FCStd b/tests/data/projekt001/involute_gear_test.FCStd similarity index 100% rename from tests/data/projekt_001/involute_gear_test.FCStd rename to tests/data/projekt001/involute_gear_test.FCStd diff --git a/tests/data/projekt_001/metafile.yaml b/tests/data/projekt001/metafile.yaml similarity index 100% rename from tests/data/projekt_001/metafile.yaml rename to tests/data/projekt001/metafile.yaml diff --git a/tests/data/projekt002/README.md b/tests/data/projekt002/README.md new file mode 100644 index 0000000..4279723 --- /dev/null +++ b/tests/data/projekt002/README.md @@ -0,0 +1,5 @@ +# projekt002 – 4 views (iso, front, top, right) + +Place **involute_gear_test.FCStd** in this folder (same directory as `metafile.yaml`). + +Reference images: `pixi run create-references` or `pixi run create-references-xvfb`. diff --git a/tests/data/projekt002/bevelgear.FCStd b/tests/data/projekt002/bevelgear.FCStd new file mode 100644 index 0000000..dc6ec9e Binary files /dev/null and b/tests/data/projekt002/bevelgear.FCStd differ diff --git a/tests/data/projekt002/metafile.yaml b/tests/data/projekt002/metafile.yaml new file mode 100644 index 0000000..91d5804 --- /dev/null +++ b/tests/data/projekt002/metafile.yaml @@ -0,0 +1,50 @@ +version: 1 +model: "bevelgear.FCStd" +description: "Involute gear – 4 orthographic/isometric views" + +default: + image_dir: "references" + image_format: "png" + threshold: 0.98 + fit_all: true + +views: + - id: "gear_iso" + label: "Isometric view" + type: "3d" + orientation: "iso" + display: + mode: "shaded" + size: [1600, 1200] + output: + filename: "gear_iso.png" + + - id: "gear_front" + label: "Front view" + type: "3d" + orientation: "front" + display: + mode: "shaded" + size: [1600, 1200] + output: + filename: "gear_front.png" + + - id: "gear_top" + label: "Top view" + type: "3d" + orientation: "top" + display: + mode: "shaded" + size: [1600, 1200] + output: + filename: "gear_top.png" + + - id: "gear_right" + label: "Right view" + type: "3d" + orientation: "right" + display: + mode: "shaded" + size: [1600, 1200] + output: + filename: "gear_right.png" diff --git a/tests/data/projekt_001/README.md b/tests/data/projekt_001/README.md deleted file mode 100644 index ef688dc..0000000 --- a/tests/data/projekt_001/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# projekt_001 – Involute gear visual test - -Place **involute_gear_test.FCStd** in this folder (same directory as `metafile.yaml`). - -Then create or update reference images: - -- **First time / missing references:** - `pixi run create-references` (or set `VISUAL_TEST_REFERENCE_MODE=create_missing` and run `pixi run test-visual`). -- **Update all references (e.g. after FreeCAD/OCC change):** - `pixi run create-references`. - -Run visual tests: `pixi run test-visual` (requires a display, or use xvfb in CI).