juli/OrcaSlicer
1
1
Fork 0
mirror of https://github.com/OrcaSlicer/OrcaSlicer.git synced 2026-09-26 02:11:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

M8a: assembly mates — Fastened + Planar (recipe v3)

Browse Source 
An assembly is a multi-body document. An instance is already expressible as
Transform with xf_copy=true, and a mate connector is already a CoordSys
feature, so this adds exactly one feature type: Mate.

No constraint solver. A mate rigidly transforms the body carrying connector B
so that B's frame lands on connector A's, applied in feature order like every
other feature. Chains resolve by composition; closed kinematic loops do not
converge (last mate wins) and are out of scope.

The vendored SolveSpace in src/libslic3r/slvs/ was evaluated for 3D extension
and rejected: it is built and linked but has zero callers, and SketchEngine's
solver is hand-rolled. Extending it would mean adopting a dependency to write
more code than the alternative.

- CadFeatureType::Mate appended; six fields (mate_kind, mate_cs_a, mate_cs_b,
  mate_offset, mate_angle, mate_flip) appended at the END of both cereal lists
- SNAPORCA_CAD_RECIPE_VERSION 2 -> 3; v2 blobs are rejected, as by design there
  is no migration path. Golden fixture renamed to cad_recipe_v3.bin and
  regenerated once, extended with two CoordSys + one Mate so the new fields are
  tripwired by the field-order assertions
- datum_frame() extracted from resolve_datum_coordsys() so a mate can resolve
  its connectors against the in-progress bodies vector during replay
- apply_mate dispatched early-return, so Mate is deliberately absent from
  starts_new (unreachable for that dispatch style)
- Planar: the degenerate branch splits on the sign of zB.z_target — antiparallel
  needs a 180 deg rotation about a perpendicular axis, which an earlier revision
  silently skipped, leaving the body's normal inverted
- MCP: mate command, named bare to match the other 38 methods

Drive-by: feature_type_name() was missing Mirror, ThickenSurface, SurfaceOffset,
SurfaceLoft and SurfaceFill, which reported as "Unknown" to MCP clients.

Suite 122 cases / 1741 assertions green. Note that kernel-test.sh builds only
libslic3r_tests, so McpControl.cpp is reviewed but not compiled here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tommaso Bianchi
2026-07-25 10:51:22 +02:00
co-authored by Claude Opus 5
parent 9c28be5860
commit b13ca01ccc
6 changed files with 838 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/libslic3r/CadDocument.cpp
+168 -39
View File
@@ -1291,6 +1291,22 @@ int CadDocument::add_coordsys(CoordSysType type, const Vec3d& point, const std::
return int(features.size()) - 1;
}
int CadDocument::add_mate(int kind, int cs_a, int cs_b, double offset, double angle_deg, bool flip,
const std::string& name)
{
CadFeature f;
f.type = CadFeatureType::Mate;
f.name = name;
f.mate_kind = kind;
f.mate_cs_a = cs_a;
f.mate_cs_b = cs_b;
f.mate_offset = offset;
f.mate_angle = angle_deg;
f.mate_flip = flip;
features.push_back(f);
return int(features.size()) - 1;
}
int CadDocument::add_helix(const SketchPlane& plane, double radius, double pitch, double height,
bool left_handed, double taper_deg, const std::string& name)
{
@@ -1627,9 +1643,10 @@ std::vector<CadDocument::DatumAxis> CadDocument::resolve_datum_axes() const
return out;
}
std::vector<CadDocument::DatumCoordSys> CadDocument::resolve_datum_coordsys() const
CadDocument::DatumCoordSys CadDocument::datum_frame(const std::vector<CadBody>& bodies, const CadFeature& f)
{
std::vector<DatumCoordSys> out;
CadDocument::DatumCoordSys ds;
ds.name = f.name;
auto resolve_face = [&](int body_idx, int face_idx) -> TopoDS_Face {
if (face_idx < 0 || body_idx < 0 || body_idx >= int(bodies.size()))
@@ -1649,45 +1666,48 @@ std::vector<CadDocument::DatumCoordSys> CadDocument::resolve_datum_coordsys() co
return true;
};
switch (f.coordsys_type) {
case CoordSysType::PointWorld: {
ds.origin = f.coordsys_point;
ds.x = Vec3d(1, 0, 0);
ds.y = Vec3d(0, 1, 0);
break;
}
case CoordSysType::FaceAndDirection: {
TopoDS_Face fc = resolve_face(f.coordsys_body, f.coordsys_face);
Vec3d p0, edge_dir;
bool have_edge = resolve_edge(f.coordsys_body, f.coordsys_edge, p0, edge_dir);
if (fc.IsNull()) { ds.error = "face not found"; break; }
ds.origin = GeometryEngine::face_centroid_world(fc);
Vec3d Z = GeometryEngine::face_normal_world(fc);
// Tentative X: edge direction if available, else the hint or a fallback.
Vec3d X_tent = have_edge ? edge_dir : f.coordsys_x_hint;
if (X_tent.squaredNorm() < 1e-18) { ds.error = "zero-length direction"; break; }
X_tent.normalize();
// Gram-Schmidt: ensure orthonormal, right-handed frame.
// Y = Z x X_tent, X = Y x Z (this makes X perpendicular to Z, not X_tent)
Vec3d Y = Z.cross(X_tent);
if (Y.squaredNorm() < 1e-12) {
// Edge/hint is parallel to Z -> X is degenerate; fall back to world X/Y orthonormalised.
Vec3d ref = (std::abs(Z.z()) < 0.9) ? Vec3d(0, 0, 1) : Vec3d(1, 0, 0);
Y = Z.cross(ref);
if (Y.squaredNorm() < 1e-12) Y = Z.cross(Vec3d(0, 1, 0));
}
Y.normalize();
ds.x = Y.cross(Z).normalized();
ds.y = Y;
break;
}
}
return ds;
}
std::vector<CadDocument::DatumCoordSys> CadDocument::resolve_datum_coordsys() const
{
std::vector<DatumCoordSys> out;
for (const CadFeature& f : features) {
if (f.type != CadFeatureType::CoordSys || !f.enabled) continue;
DatumCoordSys ds;
ds.name = f.name;
switch (f.coordsys_type) {
case CoordSysType::PointWorld: {
ds.origin = f.coordsys_point;
ds.x = Vec3d(1, 0, 0);
ds.y = Vec3d(0, 1, 0);
break;
}
case CoordSysType::FaceAndDirection: {
TopoDS_Face fc = resolve_face(f.coordsys_body, f.coordsys_face);
Vec3d p0, edge_dir;
bool have_edge = resolve_edge(f.coordsys_body, f.coordsys_edge, p0, edge_dir);
if (fc.IsNull()) { ds.error = "face not found"; break; }
ds.origin = GeometryEngine::face_centroid_world(fc);
Vec3d Z = GeometryEngine::face_normal_world(fc);
// Tentative X: edge direction if available, else the hint or a fallback.
Vec3d X_tent = have_edge ? edge_dir : f.coordsys_x_hint;
if (X_tent.squaredNorm() < 1e-18) { ds.error = "zero-length direction"; break; }
X_tent.normalize();
// Gram-Schmidt: ensure orthonormal, right-handed frame.
// Y = Z x X_tent, X = Y x Z (this makes X perpendicular to Z, not X_tent)
Vec3d Y = Z.cross(X_tent);
if (Y.squaredNorm() < 1e-12) {
// Edge/hint is parallel to Z -> X is degenerate; fall back to world X/Y orthonormalised.
Vec3d ref = (std::abs(Z.z()) < 0.9) ? Vec3d(0, 0, 1) : Vec3d(1, 0, 0);
Y = Z.cross(ref);
if (Y.squaredNorm() < 1e-12) Y = Z.cross(Vec3d(0, 1, 0));
}
Y.normalize();
ds.x = Y.cross(Z).normalized();
ds.y = Y;
break;
}
}
out.push_back(ds);
out.push_back(datum_frame(bodies, f));
}
return out;
}
@@ -2872,6 +2892,114 @@ void CadDocument::apply_project(const std::vector<CadBody>& bodies, CadFeature&
if (f.entities.empty()) throw std::runtime_error("project: produced no entities");
}
void CadDocument::apply_mate(std::vector<CadBody>& bodies, const CadFeature& f) const
{
const int nc = int(features.size());
if (f.mate_cs_a < 0 || f.mate_cs_a >= nc)
throw std::runtime_error("mate: mate_cs_a out of range");
if (f.mate_cs_b < 0 || f.mate_cs_b >= nc)
throw std::runtime_error("mate: mate_cs_b out of range");
const CadFeature& fa = features[f.mate_cs_a];
const CadFeature& fb = features[f.mate_cs_b];
if (fa.type != CadFeatureType::CoordSys || !fa.enabled)
throw std::runtime_error("mate: mate_cs_a is not a valid CoordSys feature");
if (fb.type != CadFeatureType::CoordSys || !fb.enabled)
throw std::runtime_error("mate: mate_cs_b is not a valid CoordSys feature");
CadDocument::DatumCoordSys A = datum_frame(bodies, fa);
CadDocument::DatumCoordSys B = datum_frame(bodies, fb);
if (!A.error.empty()) throw std::runtime_error("mate: " + A.error);
if (!B.error.empty()) throw std::runtime_error("mate: " + B.error);
const int tgt_body = fb.coordsys_body;
if (tgt_body < 0)
throw std::runtime_error("mate: mate_cs_b has no associated body");
if (tgt_body >= int(bodies.size()) || bodies[tgt_body].shape.IsNull())
throw std::runtime_error("mate: target body out of range or null");
Vec3d xA(A.x), yA(A.y), oA(A.origin);
Vec3d zA = xA.cross(yA).normalized();
Vec3d xB(B.x), yB(B.y), oB(B.origin);
Vec3d zB = xB.cross(yB).normalized();
auto make_4x4 = [&](const Vec3d& x, const Vec3d& y, const Vec3d& z, const Vec3d& o) {
gp_Trsf T;
T.SetValues(x.x(), y.x(), z.x(), o.x(),
x.y(), y.y(), z.y(), o.y(),
x.z(), y.z(), z.z(), o.z());
return T;
};
gp_Trsf M_A = make_4x4(xA, yA, zA, oA);
gp_Trsf M_B = make_4x4(xB, yB, zB, oB);
gp_Trsf F;
if (f.mate_flip) {
// Rx(pi): flip y→-y, z→-z
F.SetValues(1, 0, 0, 0,
0, -1, 0, 0,
0, 0, -1, 0);
}
gp_Trsf T;
if (f.mate_kind == 0) {
// Fastened: T = M_A * Rz(mate_angle) * Tz(mate_offset) * F * M_B^-1
gp_Trsf Rz;
Rz.SetRotation(gp_Ax1(gp_Pnt(0,0,0), gp_Dir(0,0,1)), f.mate_angle * M_PI / 180.0);
gp_Trsf Tz;
Tz.SetTranslation(gp_Vec(0, 0, f.mate_offset));
gp_Trsf M_B_inv = M_B.Inverted();
T = M_A * Rz * Tz * F * M_B_inv;
} else {
// Planar (mate_kind == 1): align normals only, preserve in-plane pose
Vec3d z_target = f.mate_flip ? -zA : zA;
double ddot = zB.dot(z_target);
Vec3d rot_axis;
double rot_angle = 0;
if (ddot <= -0.9999) {
// Anti-parallel: 180° rotation about any axis perpendicular to zB
Vec3d ref = (std::abs(zB.z()) < 0.9) ? Vec3d(0, 0, 1) : Vec3d(1, 0, 0);
rot_axis = zB.cross(ref).normalized();
rot_angle = M_PI;
} else {
rot_axis = zB.cross(z_target);
if (rot_axis.squaredNorm() > 1e-18) {
rot_axis.normalize();
rot_angle = std::acos(std::max(-1.0, std::min(1.0, ddot)));
}
}
gp_Trsf R_align;
if (rot_angle > 1e-12) {
R_align.SetRotation(gp_Ax1(gp_Pnt(oB.x(), oB.y(), oB.z()),
gp_Dir(rot_axis.x(), rot_axis.y(), rot_axis.z())),
rot_angle);
}
gp_Trsf Rz_about_target;
if (std::abs(f.mate_angle) > 1e-12) {
Rz_about_target.SetRotation(
gp_Ax1(gp_Pnt(oB.x(), oB.y(), oB.z()),
gp_Dir(z_target.x(), z_target.y(), z_target.z())),
f.mate_angle * M_PI / 180.0);
}
gp_Trsf R = Rz_about_target * R_align;
double d = (oB - oA).dot(zA);
Vec3d offset_vec = zA * (f.mate_offset - d);
T.SetValues(1, 0, 0, offset_vec.x(),
0, 1, 0, offset_vec.y(),
0, 0, 1, offset_vec.z());
T = T * R;
}
BRepBuilderAPI_Transform xform(bodies[tgt_body].shape, T, true /*copy*/);
if (!xform.IsDone()) throw std::runtime_error("mate: transform failed");
bodies[tgt_body].shape = xform.Shape();
}
void CadDocument::route_feature(std::vector<CadBody>& bodies, const CadFeature& f) const
{
if (f.type == CadFeatureType::Plane) return; // datum plane: not part of the body pipeline
@@ -2882,6 +3010,7 @@ void CadDocument::route_feature(std::vector<CadBody>& bodies, const CadFeature&
if (f.type == CadFeatureType::Cut) { apply_cut(bodies, f); return; } // plane-split body
if (f.type == CadFeatureType::Mirror) { apply_mirror(bodies, f); return; } // mirror body about plane
if (f.type == CadFeatureType::Transform) { apply_transform(bodies, f); return; } // move/rotate body
if (f.type == CadFeatureType::Mate) { apply_mate(bodies, f); return; } // assembly mate
if (f.type == CadFeatureType::Thicken) { apply_thicken(bodies, f); return; } // face -> plate
if (f.type == CadFeatureType::ThickenSurface) { apply_thicken_surface(bodies, f); return; }
if (f.type == CadFeatureType::SurfaceOffset) { apply_surface_offset(bodies, f); return; }
src/libslic3r/CadDocument.hpp
+20 -6
View File
@@ -19,7 +19,7 @@
namespace Slic3r {
enum class CadFeatureType { Sketch, Extrude, Fillet, Chamfer, Hole, Thread, Shell, Revolve, Sweep, Pattern, Plane, Loft, Draft, Import, Boolean, Cut, Mirror, Axis, CoordSys, Helix, Transform, Thicken, Project, DeleteFace, Rib, SurfaceExtrude, SurfaceRevolve, ThickenSurface, SurfaceOffset, SurfaceLoft, SurfaceFill };
enum class CadFeatureType { Sketch, Extrude, Fillet, Chamfer, Hole, Thread, Shell, Revolve, Sweep, Pattern, Plane, Loft, Draft, Import, Boolean, Cut, Mirror, Axis, CoordSys, Helix, Transform, Thicken, Project, DeleteFace, Rib, SurfaceExtrude, SurfaceRevolve, ThickenSurface, SurfaceOffset, SurfaceLoft, SurfaceFill, Mate };
enum class SketchShape { Rectangle, Circle };
enum class PlaneType { Offset, Angle, Midplane, Tangent, TwoEdges, Coincident };
enum class AxisType { TwoPoints, FaceNormal, CylinderCenterline, PlaneIntersection, AlongEdge };
@@ -295,6 +295,14 @@ struct CadFeature {
double rib_thickness{2}; // wall thickness (mm), centred on the line
double rib_depth{10}; // extrude distance along the sketch-plane normal (mm)
// --- Mate (assembly) ---
int mate_kind{0}; // 0 = Fastened, 1 = Planar (M8b adds 2/3/4)
int mate_cs_a{-1}; // feature index of the FIXED CoordSys (mate connector A)
int mate_cs_b{-1}; // feature index of the CoordSys on the body that MOVES
double mate_offset{0}; // translation along A's z, mm
double mate_angle{0}; // rotation about A's z, degrees
bool mate_flip{false}; // oppose the two z axes (face-to-face)
template<class Archive>
void save(Archive& ar) const {
std::string brep = (type == CadFeatureType::Import) ? brep_to_string(imported_solid) : std::string();
@@ -329,8 +337,9 @@ struct CadFeature {
hole_style, hole_cbore_diameter, hole_cbore_depth,
hole_csink_diameter, hole_csink_angle, hole_standard,
rib_sketch_ref, rib_entity, rib_thickness, rib_depth,
pattern_curve_sketch, pattern_curve_entity,
expr);
pattern_curve_sketch, pattern_curve_entity,
expr,
mate_kind, mate_cs_a, mate_cs_b, mate_offset, mate_angle, mate_flip);
}
template<class Archive>
void load(Archive& ar) {
@@ -366,8 +375,9 @@ struct CadFeature {
hole_style, hole_cbore_diameter, hole_cbore_depth,
hole_csink_diameter, hole_csink_angle, hole_standard,
rib_sketch_ref, rib_entity, rib_thickness, rib_depth,
pattern_curve_sketch, pattern_curve_entity,
expr);
pattern_curve_sketch, pattern_curve_entity,
expr,
mate_kind, mate_cs_a, mate_cs_b, mate_offset, mate_angle, mate_flip);
imported_solid = brep_from_string(brep);
}
};
@@ -528,6 +538,8 @@ public:
int add_axis(AxisType axis_type, const std::string& name);
// Datum coordinate system.
int add_coordsys(CoordSysType type, const Vec3d& point, const std::string& name);
int add_mate(int kind, int cs_a, int cs_b, double offset, double angle_deg, bool flip,
const std::string& name);
int add_helix(const SketchPlane& plane, double radius, double pitch, double height,
bool left_handed, double taper_deg, const std::string& name);
// Build the helix wire from a Helix feature's params (exposed for tests).
@@ -550,7 +562,7 @@ public:
// - bump this whenever CadFeature::save/load gains or loses a field
// - v1 blobs are deliberately not loadable; there is no migration path by design
// - append fields ONLY at the end of save/load, never reorder (golden fixture enforces this)
static constexpr uint32_t SNAPORCA_CAD_RECIPE_VERSION = 2;
static constexpr uint32_t SNAPORCA_CAD_RECIPE_VERSION = 3;
std::string serialize_recipe() const;
bool deserialize_recipe(const std::string& blob);
@@ -634,6 +646,8 @@ private:
void apply_thicken_surface(std::vector<CadBody>& bodies, const CadFeature& f) const;
void apply_surface_offset(std::vector<CadBody>& bodies, const CadFeature& f) const;
void apply_project(const std::vector<CadBody>& bodies, CadFeature& f) const;
static DatumCoordSys datum_frame(const std::vector<CadBody>& bodies, const CadFeature& f);
void apply_mate(std::vector<CadBody>& bodies, const CadFeature& f) const;
// Undo/redo stacks of feature-list snapshots. checkpoint() pushes onto m_undo and
// clears m_redo; undo()/redo() shuffle the current state between them. Capped so a
src/slic3r/GUI/McpControl.cpp
+35
View File
@@ -71,6 +71,7 @@ const char* feature_type_name(CadFeatureType t)
case CadFeatureType::Import: return "Import";
case CadFeatureType::Boolean: return "Boolean";
case CadFeatureType::Cut: return "Cut";
case CadFeatureType::Mirror: return "Mirror";
case CadFeatureType::Axis: return "Axis";
case CadFeatureType::CoordSys: return "CoordSys";
case CadFeatureType::Helix: return "Helix";
@@ -81,6 +82,11 @@ const char* feature_type_name(CadFeatureType t)
case CadFeatureType::Rib: return "Rib";
case CadFeatureType::SurfaceExtrude: return "SurfaceExtrude";
case CadFeatureType::SurfaceRevolve: return "SurfaceRevolve";
case CadFeatureType::ThickenSurface: return "ThickenSurface";
case CadFeatureType::SurfaceOffset: return "SurfaceOffset";
case CadFeatureType::SurfaceLoft: return "SurfaceLoft";
case CadFeatureType::SurfaceFill: return "SurfaceFill";
case CadFeatureType::Mate: return "Mate";
}
return "Unknown";
}
@@ -324,6 +330,15 @@ json describe_tools()
json{{"name", "angle"}, {"type", "number"}, {"unit", "deg"}, {"default", 360}},
json{{"name", "axis"}, {"type", "integer"}, {"enum", json::array({0, 1})}, {"default", 0}},
})}},
json{{"name", "mate"}, {"summary", "Mate two bodies: transform the moving body (cs_b) so its connector lands on the fixed one (cs_a). kind: 0=Fastened, 1=Planar."},
{"params", json::array({
json{{"name", "kind"}, {"type", "integer"}, {"default", 0}, {"description", "0=Fastened (full align), 1=Planar (normal only)"}},
json{{"name", "cs_a"}, {"type", "integer"}, {"description", "feature index of the fixed CoordSys (mate connector A)"}},
json{{"name", "cs_b"}, {"type", "integer"}, {"description", "feature index of the CoordSys on the body that moves"}},
json{{"name", "offset"}, {"type", "number"}, {"unit", "mm"}, {"default", 0}},
json{{"name", "angle"}, {"type", "number"}, {"unit", "deg"}, {"default", 0}},
json{{"name", "flip"}, {"type", "boolean"}, {"default", false}},
})}},
json{{"name", "query_topology"}, {"summary", "Measured faces (centroid/normal/cylinder) and edges (length/circle) of a body."},
{"params", json::array({
json{{"name", "body"}, {"type", "integer"}, {"default", 0}},
@@ -1310,6 +1325,25 @@ json action_helix(DesignPanel* panel, const json& params)
return json{{"ok", true}, {"helix_index", idx}, {"bodies", int(doc.bodies.size())}, {"error", doc.error}};
}
json action_mate(DesignPanel* panel, const json& params)
{
if (!params.contains("cs_a")) throw std::runtime_error("mate needs 'cs_a' (CoordSys feature index)");
if (!params.contains("cs_b")) throw std::runtime_error("mate needs 'cs_b' (CoordSys feature index)");
const int kind = params.value("kind", 0);
const int cs_a = params["cs_a"].get<int>();
const int cs_b = params["cs_b"].get<int>();
const double offset = params.value("offset", 0.0);
const double angle = params.value("angle", 0.0);
const bool flip = params.value("flip", false);
CadDocument& doc = panel->mcp_doc();
doc.checkpoint();
int idx = doc.add_mate(kind, cs_a, cs_b, offset, angle, flip, "Mate");
bool ok = doc.recompute();
if (!ok) doc.undo();
panel->mcp_after_change();
return json{{"ok", ok}, {"mate_index", idx}, {"bodies", int(doc.bodies.size())}, {"error", doc.error}};
}
json action_set_variable(DesignPanel* panel, const json& params)
{
if (!params.contains("name")) throw std::runtime_error("set_variable needs 'name'");
@@ -1394,6 +1428,7 @@ std::string handle_on_main(const std::string& method, const json& params, const
if (method == "surface_offset") return rpc_result(id, action_surface_offset(panel, params));
if (method == "surface_loft") return rpc_result(id, action_surface_loft(panel, params));
if (method == "surface_fill") return rpc_result(id, action_surface_fill(panel, params));
if (method == "mate") return rpc_result(id, action_mate(panel, params));
return rpc_error(id, -32601, "Unknown method: " + method);
} catch (const Standard_Failure& ex) { // OCCT errors are NOT std::exception
return rpc_error(id, -32000, std::string("OCCT: ") + (ex.GetMessageString() ? ex.GetMessageString() : "failure"));