Skip to content

armgit / SOMA

Public Imported from GitHub
0

Desktop app for designing parametric 3D models in CadQuery together with the coding agent of your choice

Doku: Schraubbahn, Warnungen zur Bewegung und alpha in Skill, Vorlage und Changelog

Kai-Jungsthoefel4d7c79bfc2dd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd0e73b..38fd5fc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,19 @@ the version is bumped.
## [Unreleased]
+### Added
+
+- `soma anim build`, `info` and `check` warn about motion that plays back differently than written: jumps within one frame, turns so fast that they wobble between frames, and parts that are still hidden at the end.
+- `add_part(..., alpha=)` sets the opacity of a part. A reference with `alpha=1` is opaque, for scenery in animations such as a floor or a logo, and still stays out of `soma export --all`.
+
+### Changed
+
+- Free parts moved with `to()` in an animation follow a rigid-body screw path: a turn runs on the arc about its axis instead of wobbling around the model origin. Animations that combine a large turn with a large shift in one `to()` take a different path than before.
+
+### Fixed
+
+- Long animations with many steps build much faster (a two-minute animation in seconds instead of many minutes), so the app shows them again.
+
## [0.9.0] - 2026-10-16
### Added
diff --git a/app/resources/skills/animation.md b/app/resources/skills/animation.md
index 78d94e9..ed7e0e5 100644
--- a/app/resources/skills/animation.md
+++ b/app/resources/skills/animation.md
@@ -33,7 +33,9 @@ a.wait(1)
## Joints and timeline
- `hinge(parts, p1, p2)`: angle in degrees, right-hand rule around `p2 - p1`. `slider(parts, direction)`: way in mm.
- `part(parts)`: free motion with `to(cq.Location(...))`, `translate((x, y, z))`, `rotate(p1, p2, angle)`.
+ `part(parts)`: free motion with `to(cq.Location(...))`, `translate((x, y, z))`, `rotate(p1, p2, angle)`. `to()`
+ moves like a rigid body on a screw path: a pure turn runs on the arc about its axis (at most 180°), a pure shift
+ straight. Do not build your own interpolation from many tiny steps for that.
- `parts` is a name from `add_part`, a group (`"Housing"`, `"Housing/Screws"`), a part with its group (`"Housing/Lid"`) or a list. One joint per part. A joint
on a moving part gets `parent=lid`, its axis is given in the model position.
- `joint.to(value)` (0 = as modelled), `joint.by(delta)`.
@@ -55,8 +57,11 @@ Captions: one short sentence in the language the user speaks, about what moves a
## Build, check, look
-1. `soma anim build` (the app also builds when the file changes). Errors name file and line.
-2. `soma anim info "Open the lid"`: the timeline as text. Read it.
+1. `soma anim build` (the app also builds when the file changes). Errors name file and line. It also warns about
+ motion that plays back differently than written: jumps within one frame (`run_time=0`, a camera `set()` in the
+ middle), turns faster than about 15° per frame that wobble between the 30 samples per second, and parts still
+ hidden at the end (also through `hide()` of a group). Fix them or make sure they are intended.
+2. `soma anim info "Open the lid"`: the timeline and the warnings as text. Read it.
3. `soma anim check "Open the lid" --gap 0.5`: parts that collide or come closer than the gap during the motion. Fix
collisions in the model or in the motion. Contacts and gaps as built in the model count as intended, only what
gets worse during the motion is reported. A motion built from many short `play()` steps (a coupled mechanism)
diff --git a/app/resources/template/AGENTS.md b/app/resources/template/AGENTS.md
index c37fedb..47c5b9f 100644
--- a/app/resources/template/AGENTS.md
+++ b/app/resources/template/AGENTS.md
@@ -26,7 +26,7 @@ The app shows the result in a 3D viewer next to this terminal. Notes and wishes
2. **Register every part**: `add_part("Name", workplane_or_shape)`. Unregistered geometry is invisible in the viewer and missing from exports.
3. Names are unique. Umlauts are fine, they are shown as written.
4. Group related parts with `group`: `add_part("Screw front", screw, group="Housing/Screws")` (nested with `/`). Groups show up in the part tree of the app and as sub-assemblies in `output/model.step`.
-5. Mark a part the user brought (for example a circuit board) with `role="reference"`: it is shown semi-transparent and skipped by `soma export --all`. Cut clearances around it, but do not export it.
+5. Mark a part the user brought (for example a circuit board) with `role="reference"`: it is shown semi-transparent and skipped by `soma export --all`. Cut clearances around it, but do not export it. Scenery for an animation or a video (a floor, a stand, a logo) is a reference too: give it `alpha=1` and a `color` to make it opaque.
6. Units are millimetres, Z is up, the front faces −Y (the front view looks from −Y), X points right. Put dimensions in named constants at the top of `model.py` so the user can ask for changes ("make the wall 3 mm"). Once parts live in `parts/`, the constants go to `parts/params.py`, and `model.py` and the part modules import them from there.
7. **Parameters for the user**: make the values the user would want to change themselves with `param()`: `BORE = param(38.0, "Cylinder bore", min=30, max=42, step=0.5, unit="mm", group="Crank train")`. They appear in the app's Parameters panel, where the user changes them without you. Good parameters are main dimensions, counts, options and positions (`CRANK = param(0, "Crank angle", min=0, max=360, unit="deg")`), usually 3 to 15 per model. Helper and derived values stay plain constants. Choose `min` and `max` so that the model builds and makes sense over the whole range. The default decides the field: `param(18, ...)` whole numbers, `param(True, ...)` a switch, `param("M3", ..., options=["M3", "M4"])` a choice. The user's values are kept in `parameters.json` and take the place of the defaults in the code, `soma build` lists them ("set by the user in the app"). So the number in the code is not always the one in the model. Do not edit `parameters.json` unless the user asks. If the user asks you for a new value of a parameter they set in the panel, change the default in the code and remove its entry from `parameters.json`, so that the code's value applies again.
8. Load user files with `import_step("inputs/board.step")`: this merges the whole file into one shape. If the file has several parts or sub-assemblies, keep them with `asm = import_assembly("inputs/board.step")` and `add_part("Board", asm, role="reference")`: every body becomes its own part with its name and color, the sub-assemblies become groups under "Board". Move an assembly with `asm.loc = cq.Location((x, y, z))`. STEP files often have their origin in a corner: check the bounding box and move the part deliberately.