Merge branch 'main' into feat/printer-agent-infra

docs/HLSD/multiline-infill.md

@@ -40,6 +40,12 @@ The pattern is phased on fixed positions, so it lines up across layers and
 across the regions of one layer. Rounding the corners with
 `sparse_infill_smooth_factor` happens before `multiline_fill()`.
 
+Each region builds only the rows over its bounding box in that frame, and
+outlines only the centerlines within `d1 / 2` of it, the ones whose outlines
+reach it. Every row is monotone along its direction, so each outline is started
+on the cap at the first end of its centerline, outside the region, and clipping
+to the region cuts it only where it crosses the boundary.
+
 ## Cubic
 
 Single-line Cubic draws the three families at the same spacing `h` and shifts

docs/HLSD/precise-seam.md

@@ -0,0 +1,239 @@
+# Precise Seam — High Level Design
+
+## Purpose and scope
+
+Precise Seam places the seam where a helper volume intersects the external
+wall. The user attaches a mesh to an object as a Precise Seam modifier, and on
+every layer the seam placer reads the modifier's slice to decide where the seam
+of each external perimeter may, must or must not go. The same mesh keeps
+working after the model changes, so the seam does not have to be repainted
+after every design revision, and a swept helper body can guide the seam along
+any path.
+
+The modifier is non-printing geometry. It does not take part in slicing, region
+assignment, filament selection or brim adhesion. It affects only seam
+placement, which runs during G-code export.
+
+## Volume types and priority
+
+Precise Seam adds six `ModelVolumeType` values after `SUPPORT_ENFORCER`. The
+strong types come first and the weak types follow. `is_precise_seam()`,
+`is_precise_seam_strong()` and `is_precise_seam_weak()` are range checks that
+depend on this order.
+
+| Type | Group | Effect on the perimeter |
+| --- | --- | --- |
+| `PRECISE_SEAM_CENTER` | strong | seam at the arc-length midpoint of the intersection |
+| `PRECISE_SEAM_LEFT` | strong | seam at the first point of the intersection |
+| `PRECISE_SEAM_RIGHT` | strong | seam at the last point of the intersection |
+| `PRECISE_SEAM_ENFORCED` | weak | intersection marked as enforced |
+| `PRECISE_SEAM_BLOCKED` | weak | intersection marked as blocked |
+| `PRECISE_SEAM_NEUTRAL` | weak | intersection reset to neutral |
+
+A strong modifier fixes one point. A weak modifier only changes the
+enforced/blocked type of seam candidates, and the configured seam position then
+chooses among them. First and last are taken along the perimeter made
+counter-clockwise seen from above. On an outer wall seen from outside, Left is
+the left end of the intersection. On the wall of a hole seen from inside the
+hole, the two ends are swapped.
+
+The order of volumes in the object is the priority order, highest first.
+`ModelObject::sort_volumes()` keeps every strong modifier before every weak one
+and preserves the user's order within each group. The object list lets the user
+drag a modifier only within its own group. A type change that crosses a group
+boundary moves the volume to the end of its new group, where it has the lowest
+priority. Strong modifiers are tried in this order, and the first one that
+yields a seam on a perimeter wins. Weak modifiers are applied from the lowest
+priority to the highest, so the highest one overwrites any overlapping zone.
+
+## Model storage and 3MF compatibility
+
+Projects must stay readable by earlier releases, and the modifier must not
+change a print there. Both 3MF writers therefore store a Precise Seam volume as
+an ordinary parameter modifier: `modifier_part` in the Bambu-format part
+subtype, and `ParameterModifier` together with the legacy `modifier` flag in
+the Prusa-format volume metadata. The seam mode is written separately under
+`precise_seam_type`, using the names from `ModelVolume::type_to_string()`
+(`precise_seam_center` and so on).
+
+On load, the mode applies after all other volume metadata, regardless of XML
+key order, and only when the base type is a modifier. Missing or unknown modes
+leave an ordinary modifier. Seam metadata on any other base type is ignored.
+Files that stored the seam mode directly as the volume type still load.
+
+A Precise Seam volume keeps any per-volume settings it had as a part or
+modifier, but they are inactive and the object list shows no settings item for
+it. The writers prefix these keys with `precise_seam_config:`, so an earlier
+reader drops them as unknown options. The volume therefore loads there as a
+modifier without settings and has no effect on the print. The current reader
+restores the keys only when the volume ends up as a Precise Seam type, so the
+settings return when the user changes the type back. Configuration values are
+XML-escaped in both writers, for every volume type.
+
+## Print invalidation
+
+`Print::apply()` compares the Precise Seam volumes of each object by type, ID
+and transformation. Adding, removing, moving, reordering or retyping one
+cancels background processing and invalidates only `psGCodeExport`; the sliced
+layers are kept. `model_volume_list_update_supports_and_seams()` then brings
+the support and Precise Seam volumes of the print's model copy in line with the
+new model in one pass. A volume may switch between the two families, since
+neither affects slicing. A conversion to or from a part or ordinary modifier
+changes the solid and modifier volume lists and reslices as before.
+
+## Modifier slices
+
+`SeamPlacer::init()` collects the Precise Seam volumes of each object once:
+strong ones in priority order and weak ones reversed. It slices each volume
+separately with `PrintObject::slice_single_volume()`, which shares
+`slice_modifier_volumes()` with support blockers and enforcers but does not
+merge volumes, so each keeps its own priority. The result is cached per volume
+and indexed by object layer; `Layer::id()` includes raft layers, which are
+subtracted. Seam candidates are then gathered in parallel over the layers and
+read the cache without locking.
+
+Objects without Precise Seam volumes follow the unchanged seam placement path.
+For objects that have them, perimeter extraction also removes consecutive
+duplicate points and the repeated closing point of each extrusion loop.
+Zero-length edges at path junctions would otherwise prevent point insertion
+there. Distinct visits to one point of a self-touching contour are kept.
+
+## Finding the wall segment
+
+The seam placer works on the external perimeter loops of each layer, both
+outer contours and holes, each made counter-clockwise. For every modifier
+polygon on the layer that overlaps the perimeter's bounding box, the region
+enclosed by the perimeter is clipped against the modifier polygon. The boundary
+of each intersection polygon alternates between runs that follow the perimeter
+and runs that follow the modifier outline. The wall segment is the longest
+continuous run of intersection vertices that lie on the perimeter, measured in
+vertices.
+
+The fast path first finds an intersection vertex that exactly matches a
+perimeter vertex. It then walks forward and backward, expecting the adjacent
+perimeter vertex and falling back to projection when Clipper has merged or
+split collinear edges. A vertex counts as on the perimeter when its projection
+is within about 1.6 nm, which covers Clipper's rounding. If no vertex matches
+exactly, or every vertex lies on the perimeter, the general path projects all
+vertices. When every vertex is on the perimeter, the edge midpoints are checked
+instead: a modifier chord can join two perimeter vertices directly, and the
+chords split the vertex ring into runs. If no edge leaves the perimeter, the
+perimeter lies entirely inside the modifier.
+
+`Polygon::point_projection()` optionally reports the edge that holds the
+projection, and every point of the segment keeps the index of its perimeter
+edge. New points are inserted on that edge. A point within 1 µm of an existing
+vertex snaps to that vertex instead.
+
+## Strong modifiers
+
+For a strong modifier, the target is the first point, the last point or the
+arc-length midpoint of the segment. The midpoint is projected back onto the
+original perimeter, because Clipper may have merged several perimeter edges
+into one segment edge. The target is inserted into the perimeter, and a helper
+point is inserted 1 µm before and after it. Strong modifiers are tried in
+priority order, the first valid intersection decides the seam, and weak
+modifiers are not processed for that perimeter.
+
+When candidates are built, the inserted point is the only enforced candidate
+and becomes the central enforcer; every other candidate is blocked. The seam
+position modes then pick that point: Aligned and Aligned Back prefer the central
+enforcer, while Back, Random and Nearest rank enforced candidates above blocked
+ones. Alignment and random placement can still move the final position along an
+edge. After alignment, `restore_precise_seam_positions()` writes the exact point
+and its index back into every perimeter that has a strong seam. Inner walls take
+their seam from the external seam as usual, including staggering.
+
+## Weak modifiers
+
+Weak modifiers produce one segment per intersection polygon, so one modifier can
+mark several zones on one perimeter. All segment boundaries are inserted into
+the perimeter in order of decreasing arc length. Each insertion then leaves the
+indices of the pending, shorter ones unchanged; a point on the closing edge is
+appended rather than inserted at index zero. A helper point is added 1 µm
+outside each boundary. Random placement picks a position along the edge that
+follows a candidate. These helpers keep that edge 1 µm long at each boundary, so
+a zone cannot extend or intrude further than that. Boundaries that coincide
+share their helper points.
+
+The zone types are then resolved in priority order, and the edges of enforced
+zones are subdivided into steps of at most
+`SeamPlacer::enforcer_oversampling_distance` (0.2 mm). The middle candidate of
+the longest enforced patch is therefore close to the geometric middle of the
+zone. That patch is measured in candidates, across the closing edge, regardless
+of where the contour starts; the same rule applies to painted seams.
+
+Candidates first receive their type from seam painting. The weak zones then
+overwrite it, lowest priority first. Blocked and Enforced zones therefore take
+precedence over painting, and Neutral clears painting inside its zone.
+
+## Unsupported geometry and warnings
+
+Some modifier shapes cannot be resolved to one seam or one zone per crossing.
+They are detected cheaply and reported rather than guessed:
+
+- A strong modifier that crosses a perimeter in more than one place uses only
+  its first valid segment. The other crossings are ignored.
+- A modifier that crosses the whole region enclosed by the perimeter is
+  detected when the modifier outline minus that region leaves more than one
+  piece, none of them a hole. Its intersection holds two wall runs, and only
+  one of them is used.
+- A modifier whose slice has a hole on a layer, found as a clockwise polygon in
+  the flattened slice, is skipped on that layer. The flattened slice no longer
+  records which hole belongs to which contour.
+- A perimeter that lies entirely inside a modifier is ignored by that modifier.
+
+The conditions are atomic flags shared by all layers and objects. After all
+objects are processed, `SeamPlacer::init()` issues at most one non-critical
+warning with the ID `SlicingPreciseSeamWarning`. The warning is a single line
+that lists every cause found, because the export warnings dialog shows only the
+first line of each warning. Repeated warning events replace this notification
+instead of appending text to it.
+
+## User interface
+
+- *Add Precise Seam* in the object menu creates a Center modifier from a
+  primitive or a loaded mesh. Text and SVG volumes cannot become Precise Seam
+  modifiers: the menu does not offer them, and `ObjectList::set_volume_type()`
+  refuses the change.
+- *Change Type* has a single *Precise Seam* entry. It converts other volumes to
+  Center and keeps the mode of volumes that are already Precise Seam. The
+  *Precise Seam Type* submenu appears only when every selected item is a
+  Precise Seam volume, including settings rows that resolve to one. It sets the
+  chosen mode on all selected volumes.
+- Each mode has its own icon in the object list and its own color in the 3D
+  view, at 60% opacity: warm oranges for the strong modes, and green, red and
+  gray for Enforced, Blocked and Neutral.
+- Object list drops map visible rows to volume indices while skipping hidden
+  cut connectors, and they refresh the row-to-volume map of the object.
+- Precise Seam volumes have no filament, block pasting into SLA, and are exposed
+  to Python plugins as `ModelVolumeType` values plus the `is_precise_seam*()`
+  methods.
+
+## Implementation and verification
+
+- [PreciseSeam.cpp](../../src/libslic3r/GCode/PreciseSeam.cpp) implements segment
+  detection, point insertion, weak-zone resolution and position restoration.
+  [SeamPlacer.cpp](../../src/libslic3r/GCode/SeamPlacer.cpp) integrates it into
+  candidate gathering and issues the warning.
+- [Model.hpp](../../src/libslic3r/Model.hpp) defines the types and their order,
+  [PrintApply.cpp](../../src/libslic3r/PrintApply.cpp) handles invalidation, and
+  [PrintObjectSlice.cpp](../../src/libslic3r/PrintObjectSlice.cpp) slices the
+  modifiers. [bbs_3mf.cpp](../../src/libslic3r/Format/bbs_3mf.cpp) and
+  [3mf.cpp](../../src/libslic3r/Format/3mf.cpp) store them.
+- [GUI_Factories.cpp](../../src/slic3r/GUI/GUI_Factories.cpp) and
+  [GUI_ObjectList.cpp](../../src/slic3r/GUI/GUI_ObjectList.cpp) provide the menus,
+  type changes and ordering.
+- [Precise Seam tests](../../tests/fff_print/test_precise_seam.cpp) cover the
+  strong positions, including a midpoint on an existing vertex or the closing
+  edge. They also cover shared and coincident weak boundaries, every warning,
+  and the priority order.
+- [Seam placer tests](../../tests/fff_print/test_seam_placer.cpp) cover
+  enforced-patch selection independent of the contour start, fully painted
+  contours, duplicate removal, and `Print::apply()` synchronization through
+  type changes and restored model snapshots.
+- [3MF tests](../../tests/libslic3r/test_precise_seam_3mf.cpp) cover the round
+  trip of every mode and of inactive settings, attribute escaping, and which
+  metadata combinations restore a seam mode.
+  [Plugin tests](../../tests/slic3rutils/test_precise_seam_plugin.cpp) cover the
+  Python bindings.

docs/HLSD/preset-cache.md

@@ -28,8 +28,8 @@ Per-vendor granularity is what makes the system practical:
 - A vendor whose profile is bumped invalidates only its own cache. The other 60-odd
   vendors keep theirs — even when the bumped vendor is the shared Orca filament
   library everyone else inherits from.
-- The setup wizard, which loads vendors one at a time, gets the same speedup as
-  startup without a second code path.
+- The setup wizard loads its vendors through the same routine as startup, so it
+  gets the same speedup without a second code path.
 - A vendor with no cache, or a broken one, costs only that vendor a parse.
 
 A cache holds *system* presets only. User presets, project settings and modified
@@ -162,15 +162,20 @@ cache nothing can invalidate is worse than no cache.
 
 Vendors load in a fixed order, because filament inheritance crosses exactly one
 boundary: any vendor's filament may inherit from the shared Orca filament library,
-and nothing else reaches across vendors — an `include` is always vendor-local. The
-library therefore goes first, alone; every other vendor follows in parallel, resolving
-against it; and the results are merged in a stable order:
+and nothing else reaches across vendors — an `include` is always vendor-local. Only
+installing a vendor's presets crosses it; reading the vendor, from its cache or its
+JSONs, needs nothing from the library. So every other vendor is read while the library
+loads, each is installed against it as soon as both are done, and the results are
+merged in a stable order:
 
 ```mermaid
 flowchart LR
-    lib["1 · OrcaFilamentLibrary<br/>loaded first, synchronously"] --> par["2 · every other vendor in parallel,<br/>each into its own bundle, filaments<br/>resolving against the loaded library"] --> merge["3 · bundles merged into one,<br/>sequentially, in stable vendor order"]
+    lib["1 · OrcaFilamentLibrary loaded;<br/>meanwhile every other vendor read<br/>from its cache or its JSONs"] --> par["2 · every other vendor installed<br/>in parallel, each into its own bundle,<br/>filaments resolving against the library"] --> merge["3 · bundles merged into one,<br/>in one pass per collection,<br/>in stable vendor order"]
 ```
 
+`PresetBundle::load_vendors` runs these steps for startup and for the setup wizard,
+which hand it the vendors to load and the directory each is installed in.
+
 Whether a vendor comes from its cache or from a parse changes nothing in that
 order — both produce the same bundle, so cached and parsed vendors mix freely in
 one startup.
@@ -211,11 +216,12 @@ shipped cache answered first, so the profile in `<data_dir>/system/` was never p
 and its cache was never written back.
 
 Serving from a cache is not a memory-image restore. The entries are deserialized and
-then installed one by one — inheritance resolved against the presets installed before
-them and the currently loaded filament library, includes layered in, configs flattened
-onto the collection defaults, validated and registered — by the same function the JSON
-path calls straight after parsing a sub-file. An `include` layers what the included
-base states, between the parent and the preset's own keys: the base's diff against the
+then installed by `install_vendor`, the routine the JSON path hands the vendor's entries
+to once it has parsed the sub-files: inheritance resolved against the presets installed
+before them and the currently loaded filament library, includes layered in, configs
+flattened onto the collection defaults, validated and registered. An `include` layers
+what the included base states, between the parent and the preset's own keys: the base's
+diff against the
 default, taken when the base itself was installed and before the per-variant padding
 `inherits` sees, so only what a template sets reaches the presets including it. The two
 paths share everything below the parse, which is what makes a cache-loaded bundle
@@ -223,6 +229,16 @@ indistinguishable from a JSON-loaded one by construction rather than by test cov
 Installation also rebuilds each preset's file path from the local data directory, so a
 shipped cache never carries the generating machine's paths.
 
+Installing an entry is split in two. `resolve_vendor_preset` flattens it, reading only
+what is registered under the names it inherits and includes, and `commit_vendor_preset`
+registers it, the only step that writes anything shared. Entries resolve across threads
+in runs and commit in the order the vendor lists them. A run ends before an entry that
+inherits or includes one already in it, since that one's commit registers what the
+entry resolves against, so no entry in a run reads what another in it registers. An
+entry's parse messages are held until it commits. The bundle, the log's parse and
+install messages and the error count therefore come out as parsing and installing one
+entry at a time would leave them, whatever the listing order.
+
 App upgrades work because a cache normally survives one. Only a deliberate
 `CACHE_VERSION` bump makes an installed cache unreadable, and that is handled at
 install time rather than at load: a vendor whose cache this build cannot read counts
@@ -254,17 +270,20 @@ the wizard caches the *derived JSON*, not another form of the inputs:
 open, the wizard computes the current stamps (one version peek per vendor) and, when
 they match, serves the catalog from the file — no bundle built, no preset installed.
 Caching bundle inputs instead was tried and measured: rebuilding the bundle from
-per-vendor caches costs ~2 s of preset installation whatever feeds it, so only
-skipping the rebuild entirely wins.
+per-vendor caches costs over a second of preset installation whatever feeds it, so
+only skipping the rebuild entirely wins.
 
 Any change to the set — a vendor added, removed or updated, or its cache-only
 `.opc` replaced by a newer one — changes the stamps and retires the whole file;
-the wizard then rebuilds the bundle vendor by vendor (per-vendor caches serving where
-they cover) and writes the catalog back. Selections, region and per-open decorations
-are applied downstream of the cache either way, so a served catalog is
-indistinguishable from a rebuilt one. Nothing ships this file and the updater never
-touches it; it is a locally written artifact, re-derived whenever stale, written
-through a temp file and rename so half a cache is never readable.
+the wizard then rebuilds the bundle with `PresetBundle::load_vendors`, the load
+startup uses (per-vendor caches serving where they cover), and writes the catalog
+back. When a vendor fails to load, the filament library included, that open falls
+back to the wizard's own scan of the vendor JSONs, as when no bundle can be built,
+and writes nothing. Selections, region and per-open decorations are applied
+downstream of the cache either way, so a served catalog is indistinguishable from a
+rebuilt one. Nothing ships this file and the updater never touches it; it is a
+locally written artifact, re-derived whenever stale, written through a temp file and
+rename so half a cache is never readable.
 
 The cache lives under `<data_dir>/cache/`, not beside the vendors: everything that
 scans `<data_dir>/system/` treats any `.opc` there as a vendor, so a non-vendor
@@ -378,6 +397,13 @@ enumerates only `*.json` will find no vendors at all in a packaged build.
   the `CachedPreset` field list — written and read by `visit_entry` in
   `PresetCacheFormat.cpp`, one list for the save, the load and the name peek alike — or
   the cache's own layout or stamps, requires bumping `CACHE_VERSION` by hand.
+- **Adding a kind of reference between presets**, as `inherits` and `include` are:
+  parse the names into `CachedPreset` (a field change, so `CACHE_VERSION` is bumped),
+  have `install_vendor_entries` end a run before an entry that names one already in it
+  and retain what the names point at, look them up only in `resolve_vendor_preset`, and
+  register what they point at only in `commit_vendor_preset`. The listing-order test in
+  `test_vendor_cache.cpp` fails for a kind the runs do not check once its fixture uses
+  it.
 - **The dictionary indexes with a `uint16`**, so `print_config_def` may hold at most
   65535 options and one cache at most 65535 distinct enum value names.
   `CacheDictionary::save` throws past that, which surfaces when CI generates the