Picking points: right-click on the model (or hover over it and press P). Picks are numbered P1, P2, P3. A 4th pick starts a new set. Esc clears them.
Every step can be undone with Ctrl+Z. The plane tolerance (Plane menu) is how close, in model units, a vertex must be to count as on a plane - raise it for noisy scans.
""" CONTROLS = """| Rotate | left-drag |
| Pan | middle-drag, or Shift + left-drag |
| Zoom | scroll wheel |
| Roll (spin in screen plane) | Ctrl + left-drag |
| Pick a point | right-click on the model, or hover and press P |
| Ctrl+O / Ctrl+S | Open / Save |
| Ctrl+Z | Undo last transform |
| Esc | Clear picks |
| Ctrl+R | Find plane (RANSAC) - repeat for the next one |
| Ctrl+E / Ctrl+F | Refine plane / Flip plane normal |
| Ctrl+L | Level on plane |
| Ctrl+1 / Ctrl+2 / Ctrl+3 | Align to X / Align to Y / Rotate 90° |
| Ctrl+4 / Ctrl+5 | Origin to center of extents XY / XYZ |
| Ctrl+K | Scale so P1-P2 is a typed distance |
| Ctrl+T | Set plane tolerance |
| Ctrl+0 | Fit view |
| F1 | Quick start |
Level, square up, scale and re-origin STL / PLY / OBJ meshes - built for" " tidying up 3D scans before CAD or printing.
" "Plane from 3 picked points or RANSAC, least-squares refinement, edge/face" " alignment, distance-based scaling, and a saved 4x4 transform that can be" " re-applied to other files.
" f"Python {platform.python_version()} · " f"PyVista {pv.__version__} · VTK {vtk.vtkVersion.GetVTKVersion()}" f" · {API_NAME} / Qt {QT_VERSION} · NumPy {np.__version__}
") QtWidgets.QMessageBox.about(self, f"About {APP_NAME}", html) def on_model_color(self): c = QtWidgets.QColorDialog.getColor(QtGui.QColor(self.model_color), self, "Model colour") if c.isValid(): self._set_model_color(c.name()) def _set_model_color(self, color): self.model_color = color self.settings.setValue("model_color", color) if getattr(self, "mesh_actor", None) is not None: self.mesh_actor.prop.color = color self.p.render() # ---------------- loading / state ---------------- def load(self, path): mesh = pv.read(path) if not isinstance(mesh, pv.PolyData): mesh = mesh.extract_surface() if not mesh.is_all_triangles: mesh = mesh.triangulate() self.path = path self.original = mesh self.mesh = mesh.copy() self.diag = self.mesh.length self.M_total = np.eye(4) self.history = [] self.saved_M = np.eye(4) self.picks, self.plane, self.plane_source = [], None, "" self.ransac_excluded, self._faces = None, None self._set_tol(self.diag * 0.003) self.p.clear() self.p.enable_lightkit() # clear() also removes the default lights self.p.add_axes(viewport=(0.9, 0.0, 1.0, 0.12)) self.mesh_actor = self.p.add_mesh(self.mesh, color=self.model_color, specular=0.3, name="mesh") self.p.reset_camera() self.setWindowTitle(f"{APP_NAME} - {Path(path).name}") self.status("Loaded.") self._update_hint() def _need_mesh(self): if self.mesh is None: self.status("Open a file first (Ctrl+O).") return True return False def _orient(self, n, c): if self._faces is None: self._faces = face_data(self.mesh) return orient_normal(n, c, self.mesh, max(self.tol, self.diag * 0.002), self._faces) def status(self, msg): if self.mesh is not None: bb = self.mesh.bounds info = (f"{Path(self.path).name} {self.mesh.n_cells:,} triangles " f"size {bb[1] - bb[0]:.4g} x {bb[3] - bb[2]:.4g} x {bb[5] - bb[4]:.4g}") else: info = "No file loaded" self.p.add_text(f"{info}\n{msg}", position="upper_left", font_size=10, color="white", name="status") if hasattr(self, "hint_label"): self._update_hint() # ---------------- drawing ---------------- def _clear_overlays(self): for name in ("plane", "normal", "inliers", "picklabels", "measure"): self.p.remove_actor(name) for i in range(3): self.p.remove_actor(f"pick{i}") def _draw_picks(self): r = self.diag * 0.006 for i, pt in enumerate(self.picks): self.p.add_mesh(pv.Sphere(radius=r, center=pt), color=PICK_COLORS[i], name=f"pick{i}", pickable=False) if self.picks: self.p.add_point_labels( np.array(self.picks), [f"P{i + 1}" for i in range(len(self.picks))], font_size=14, text_color="white", shape_opacity=0.5, name="picklabels", always_visible=True, show_points=False, pickable=False) if len(self.picks) >= 2: self.p.add_mesh(pv.Line(self.picks[0], self.picks[1]), color="#ffffff", line_width=2, name="measure", pickable=False) def _draw_plane(self, inlier_pts=None): n, c = self.plane size = self.diag * 0.7 self.p.add_mesh(pv.Plane(center=c, direction=n, i_size=size, j_size=size), color="#f5c542", opacity=0.35, name="plane", pickable=False) self.p.add_mesh(pv.Arrow(start=c, direction=n, scale=self.diag * 0.25), color="#f5c542", name="normal", pickable=False) if inlier_pts is not None and len(inlier_pts): if len(inlier_pts) > 60000: inlier_pts = inlier_pts[ np.random.default_rng(0).choice(len(inlier_pts), 60000, False)] self.p.add_mesh(pv.PolyData(inlier_pts), color="#33d17a", point_size=3, name="inliers", pickable=False) else: self.p.remove_actor("inliers") def _draw_ground(self): bb = self.mesh.bounds span = max(bb[1] - bb[0], bb[3] - bb[2]) * 1.3 cx, cy = (bb[0] + bb[1]) / 2, (bb[2] + bb[3]) / 2 grid = pv.Plane(center=(cx, cy, 0), direction=(0, 0, 1), i_size=span, j_size=span, i_resolution=20, j_resolution=20) self.p.add_mesh(grid, style="wireframe", color="#8a8f99", opacity=0.5, name="ground", pickable=False) L = self.mesh.length * 0.12 for ax, vec, col in (("x", (L, 0, 0), "#ff5555"), ("y", (0, L, 0), "#55dd55"), ("z", (0, 0, L), "#5599ff")): self.p.add_mesh(pv.Line((0, 0, 0), vec), color=col, line_width=5, name=f"origin_{ax}", pickable=False) def _plane_summary(self): n, c = self.plane near = np.abs((self.mesh.points - c) @ n) <= self.tol return (f"{self.plane_source}: tilt from horizontal {tilt_degrees(n):.3f} deg, " f"{near.sum():,} vertices within tol.\n" "Arrow = new +Z: the part will sit on the arrow side (Ctrl+F to flip).") # ---------------- transforms ---------------- def _apply(self, M, reset_view=False): """Transform the mesh, accumulate the matrix and refresh the scene.""" self.history.append(self.M_total.copy()) self.mesh.transform(M, inplace=True) self.M_total = M @ self.M_total self.diag = self.mesh.length self.picks, self.plane, self.ransac_excluded, self._faces = [], None, None, None self._clear_overlays() self._draw_ground() if reset_view: self.p.reset_camera() self.p.view_isometric() else: self.p.render() def _set_total(self, M_total): self.mesh.copy_from(self.original.transform(M_total, inplace=False)) self.M_total = M_total self.diag = self.mesh.length self.picks, self.plane, self.ransac_excluded, self._faces = [], None, None, None self._clear_overlays() def _pivot(self): """Scale/rotate about the XY center of the part at Z=0 so a levelled base stays put.""" bb = self.mesh.bounds return np.array([(bb[0] + bb[1]) / 2, (bb[2] + bb[3]) / 2, 0.0]) # ---------------- callbacks: picking & plane ---------------- def on_pick(self, point): if point is None or self.mesh is None: return if len(self.picks) == 3: self.picks, self.plane = [], None self._clear_overlays() self.picks.append(np.asarray(point, float)) self._draw_picks() if len(self.picks) == 1: return self.status("Picked P1. Pick 2 more for a plane, or 1 more for an edge/distance.") if len(self.picks) == 2: d = self.picks[1] - self.picks[0] return self.status( f"P1-P2 distance {np.linalg.norm(d):.4f} (dx {abs(d[0]):.4f}, dy {abs(d[1]):.4f}," f" dz {abs(d[2]):.4f})") try: n, c = plane_from_points(*self.picks) except ValueError as e: return self.status(str(e)) self.plane, self.plane_source = (self._orient(n, c), c), "3-point plane" self._draw_plane() self.status(self._plane_summary()) def on_clear(self): if self._need_mesh(): return self.picks, self.plane = [], None self._clear_overlays() self.status("Cleared. Pick points, or Plane > RANSAC.") def on_flip(self): if self.mesh is None or self.plane is None: return self.status("No plane yet.") n, c = self.plane self.plane = (-n, c) self._draw_plane() self.status("Flipped. " + self._plane_summary()) def on_ransac(self): if self._need_mesh(): return pts = self.mesh.points if self.ransac_excluded is None or len(self.ransac_excluded) != len(pts): self.ransac_excluded = np.zeros(len(pts), bool) avail = ~self.ransac_excluded if avail.sum() < 3: self.ransac_excluded[:] = False avail[:] = True QtWidgets.QApplication.setOverrideCursor(QtCore.Qt.WaitCursor) try: res = ransac_plane(pts[avail], self.tol) finally: QtWidgets.QApplication.restoreOverrideCursor() if res is None or res[2].sum() < 10: self.ransac_excluded[:] = False return self.status("No further plane found - cycled back. Run RANSAC again.") n, c, mask_sub = res idx = np.flatnonzero(avail)[mask_sub] self.ransac_excluded[idx] = True self.picks = [] self._clear_overlays() self.plane, self.plane_source = (self._orient(n, c), c), "RANSAC plane" self._draw_plane(pts[idx]) rms = fit_plane_lsq(pts[idx])[2] self.status(self._plane_summary() + f" RMS {rms:.4g}" "\nGreen = supporting vertices. Ctrl+R again for the next-largest plane.") def on_refine(self): if self.mesh is None or self.plane is None: return self.status("No plane yet.") n0, c0 = self.plane pts = self.mesh.points near = np.abs((pts - c0) @ n0) <= self.tol if near.sum() < 3: return self.status("Too few vertices within tolerance - raise it (Plane > Plane" " tolerance, Ctrl+T).") sel = pts[near] if self.picks: radius = max(np.linalg.norm(p - c0) for p in self.picks) * 1.5 + self.tol local = sel[np.linalg.norm(sel - c0, axis=1) <= radius] if len(local) >= 3: sel = local n, c, rms = fit_plane_lsq(sel) if n @ n0 < 0: n = -n change = np.degrees(np.arccos(np.clip(n @ n0, -1, 1))) self.plane, self.plane_source = (n, c), "Refined plane" self._draw_plane(sel) self.status(self._plane_summary() + f"\nRefit on {len(sel):,} vertices, RMS {rms:.4g}," f" normal moved {change:.3f} deg.") def on_datum(self, state): self.status(f"Datum mode {'ON: P1 -> origin, P1->P2 -> +X' if state else 'OFF'}" " (applies when levelling a 3-point plane).") def _set_tol(self, value): self.tol = float(value) self.tol_action.setText(f"Plane &tolerance... (now {self.tol:.4g})") def on_set_tol(self): if self._need_mesh(): return val, ok = QtWidgets.QInputDialog.getDouble( self, "Plane tolerance", "How close (model units) a vertex must be to count as on the plane.\n" f"Default for this part: {self.diag * 0.003:.4g}. Raise it for noisy scans.", self.tol, self.diag * 1e-6, self.diag, 4) if ok and val > 0: self._set_tol(val) self.status(f"Plane tolerance set to {val:.4g}.") def on_apply(self): if self.mesh is None or self.plane is None: return self.status("No plane yet - pick 3 points or run RANSAC.") n, c = self.plane datum = None if self.datum_action.isChecked() and len(self.picks) == 3: datum = (self.picks[0], self.picks[1]) tilt = tilt_degrees(n) self._apply(leveling_transform(n, c, datum), reset_view=True) self.status(f"Levelled: corrected {tilt:.3f} deg of tilt{' with datum' if datum else ''}." " Plane is now Z=0.\nNext: align an edge or side face to X/Y, center," " or scale.") # ---------------- callbacks: align / origin ---------------- def on_align_axis(self, axis): if self._need_mesh(): return if self.plane is not None: n = self.plane[0] if np.hypot(n[0], n[1]) < 0.17: return self.status("That face is (nearly) horizontal, so it can't set a" " direction. Use a side face, or 2 points along an edge.") note = (f" (face is {90 - tilt_degrees(n):.1f} deg off vertical; only its heading" " was used)") if abs(n[2]) > 0.26 else "" direction, what = np.array([n[1], -n[0], 0.0]), "Face" elif len(self.picks) == 2: direction = self.picks[1] - self.picks[0] if np.hypot(direction[0], direction[1]) < self.diag * 1e-4: return self.status("P1 and P2 are stacked vertically - pick along a" " horizontal edge.") note, what = "", "Edge P1->P2" else: return self.status(f"To align to {axis}: pick 2 points along an edge, or make a" " plane on a side face (3 picks / RANSAC).") M, ang = yaw_transform(direction, axis, self._pivot()) self._apply(M) self.status(f"{what} is now parallel to {axis} (rotated {ang:+.3f} deg about Z).{note}") def on_rot90(self): if self._need_mesh(): return M, _ = yaw_transform([0.0, -1.0, 0.0], "X", self._pivot()) # +90 deg self._apply(M) self.status("Rotated 90 deg about Z.") def on_center(self, mode): if self._need_mesh(): return M = centering_transform(self.mesh.bounds, mode) t = M[:3, 3] + 0.0 self._apply(M) where = ("center of extents is at 0,0,0" if mode == "xyz" else "XY center of extents is at 0,0 (Z unchanged)") self.status(f"Moved by ({t[0]:.4g}, {t[1]:.4g}, {t[2]:.4g}): {where}.") def on_p1_origin(self): if self._need_mesh(): return if not self.picks: return self.status("Pick a point first.") M = np.eye(4) M[:3, 3] = -self.picks[0] self._apply(M) self.status("P1 is now at 0,0,0.") # ---------------- callbacks: scale ---------------- def _scale(self, factor, label): if self._need_mesh(): return self._apply(scale_transform(factor, self._pivot())) self.p.reset_camera() self.status(f"Scaled x{factor:.6g} ({label}). Scaled about the part's XY center at Z=0," " so a levelled base stays on Z=0.") def on_scale_distance(self): if self._need_mesh(): return if len(self.picks) < 2: return self.status("Pick 2 points first (right-click or P), then Scale > Set" " distance (Ctrl+K).") cur = float(np.linalg.norm(self.picks[1] - self.picks[0])) if cur <= 0: return self.status("P1 and P2 are the same point.") val, ok = QtWidgets.QInputDialog.getDouble( self, "Scale to distance", f"Current P1-P2 distance: {cur:.4f}\nNew distance:", cur, 1e-9, 1e9, 4) if not ok or val <= 0: return self._scale(val / cur, f"P1-P2 {cur:.4f} -> {val:.4f}") def on_scale_factor(self): if self._need_mesh(): return val, ok = QtWidgets.QInputDialog.getDouble( self, "Scale by factor", "Uniform scale factor:", 1.0, 1e-9, 1e9, 6) if ok and val > 0 and val != 1.0: self._scale(val, "by factor") # ---------------- callbacks: file / edit ---------------- def _confirm_discard(self): """True if it's OK to throw away the current (unsaved) result.""" if not self._dirty(): return True r = QtWidgets.QMessageBox.question( self, APP_NAME, "The aligned part hasn't been saved. Save it first?", QtWidgets.QMessageBox.Save | QtWidgets.QMessageBox.Discard | QtWidgets.QMessageBox.Cancel, QtWidgets.QMessageBox.Save) if r == QtWidgets.QMessageBox.Save: self.on_save() return True return r == QtWidgets.QMessageBox.Discard def on_open(self): if not self._confirm_discard(): return f, _ = QtWidgets.QFileDialog.getOpenFileName( self, "Open mesh", "", "Meshes (*.stl *.ply *.obj);;All files (*)") if f: try: self.load(f) except Exception as e: QtWidgets.QMessageBox.critical(self, "Could not open", str(e)) def _write(self, stl): stl = Path(stl) mtx = stl.with_name(stl.stem + "_matrix.txt") self.mesh.save(stl, binary=True) save_matrix(mtx, self.M_total, self.path) self.saved_M = self.M_total.copy() self.status(f"Saved {stl.name} and {mtx.name} in {stl.parent}") def on_save(self): if self._need_mesh(): return self._write(output_paths(self.path, self.out)[0]) def on_save_as(self): if self._need_mesh(): return default = str(output_paths(self.path, self.out)[0]) f, _ = QtWidgets.QFileDialog.getSaveFileName(self, "Save STL", default, "STL (*.stl)") if f: self._write(f if f.lower().endswith(".stl") else f + ".stl") def on_undo(self): if self._need_mesh(): return if not self.history: return self.status("Nothing to undo.") self._set_total(self.history.pop()) if self.history: self._draw_ground() else: for name in ("ground", "origin_x", "origin_y", "origin_z"): self.p.remove_actor(name) self.p.render() self.status(f"Undone. {len(self.history)} transform(s) remain.") def on_reset(self): if self._need_mesh(): return self.history = [] self._set_total(np.eye(4)) for name in ("ground", "origin_x", "origin_y", "origin_z"): self.p.remove_actor(name) self.p.reset_camera() self.status("Reset to original.") def closeEvent(self, event): if not self._confirm_discard(): event.ignore() return self.p.close() super().closeEvent(event) return AlignWindow def run_gui(path, out): from qtpy import QtWidgets app = QtWidgets.QApplication.instance() or QtWidgets.QApplication(sys.argv) win = build_window_class()(path, out) win.show() return app.exec_() if hasattr(app, "exec_") else app.exec() def main(): ap = argparse.ArgumentParser(description="Level, align, center and scale an STL.") ap.add_argument("stl", nargs="?", help="input mesh (STL/PLY/OBJ)") ap.add_argument("-o", "--out", help="output STL path (default