from __future__ import annotations
import math
import sys
import FreeCADGui
__all__ = [
"Snapper",
"draftToolBar",
"HintManager",
"InputHint",
"UserInput",
"pick",
"escape",
"finish",
"supported_modes",
"unsupported_modes",
"SNAP_TOOLBAR",
]
_SUPPORTED_MODES = ("Grid", "Endpoint", "Midpoint", "Center", "Origin", "Vertex")
_UNSUPPORTED_MODES = (
"Extension",
"Parallel",
"Perpendicular",
"Intersection",
"Angle",
"Special",
"Dimensions",
"Ortho",
"Lock",
)
_SNAP_LOCK_ID = "Draft_Snap_Lock"
_COMMAND_IDS = {
"Grid": "Draft_Snap_Grid",
"Endpoint": "Draft_Snap_Endpoint",
"Midpoint": "Draft_Snap_Midpoint",
"Center": "Draft_Snap_Center",
"Origin": "Draft_Snap_Origin",
"Vertex": "Draft_Snap_Vertex",
}
SNAP_TOOLBAR = tuple(_COMMAND_IDS[mode] for mode in _SUPPORTED_MODES)
_MODE_KINDS = {
"Endpoint": "Vertex",
"Midpoint": "EdgeMid",
"Center": "Centre",
"Origin": "Origin",
"Vertex": "Vertex",
}
_STAGE = None
_STAGE_ERROR = None
def _stage_module():
global _STAGE, _STAGE_ERROR
if _STAGE is not None:
return _STAGE
if _STAGE_ERROR is not None:
raise ImportError(_stage_error_message()) from _STAGE_ERROR
try:
import ferrocad_stage as stage
except ImportError:
try:
from ferrocad import stage as stage except Exception as exc: _STAGE_ERROR = exc
raise ImportError(_stage_error_message()) from exc
_STAGE = stage
return stage
def _stage_error_message() -> str:
return (
"FreeCADGui.Snapper needs the `ferrocad_stage` extension module. "
"Build it with `cargo build -p ferrocad_stage_py --features "
"ferrocad_stage_py/extension-module` and make the resulting library "
"importable as `ferrocad_stage` (for example by copying "
"`libferrocad_stage_py.so` to `ferrocad_stage.abi3.so` in the "
"`python/` directory)."
)
def _triple(value):
if hasattr(value, "x") and hasattr(value, "y") and hasattr(value, "z"):
return (float(value.x), float(value.y), float(value.z))
try:
x, y, z = value
except (TypeError, ValueError) as exc:
raise TypeError(
"a point must be an (x, y, z) sequence or have x/y/z attributes, "
f"got {type(value).__name__}"
) from exc
return (float(x), float(y), float(z))
def _dot(a, b):
return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
def _cross(a, b):
return (
a[1] * b[2] - a[2] * b[1],
a[2] * b[0] - a[0] * b[2],
a[0] * b[1] - a[1] * b[0],
)
def _unit(value):
x, y, z = _triple(value)
length = math.sqrt(x * x + y * y + z * z)
if length <= 1e-15:
raise ValueError("a constraint axis must be a non-zero vector")
return (x / length, y / length, z / length)
def supported_modes():
return list(_SUPPORTED_MODES)
def unsupported_modes():
return list(_UNSUPPORTED_MODES)
class _PointRequest:
__slots__ = ("callback", "args", "on_cancel", "on_finish")
def __init__(self, callback, args, on_cancel=None, on_finish=None):
self.callback = callback
self.args = tuple(args)
self.on_cancel = on_cancel
self.on_finish = on_finish
def invoke(self, point):
return self.callback(point, *self.args)
class _Snapper:
def __init__(self):
self.ui = None
self._mask = list(_SUPPORTED_MODES)
self.selectMode = False
self.affinity = 1.0
self.grid = True
self.snapInfo = None
self.holdPoints = []
self.pointConstraintProvider = None
self.basepoint = None
self.constraintAxis = None
self.running = False
self._enabled = True
self._pending = None
self._minor = 1.0
self._major = 10.0
self._base_workplane = None
self._angle = 0.0
self.hint = ""
@property
def mask(self):
return self._mask
@mask.setter
def mask(self, value):
if value is None:
self._mask = []
return
if isinstance(value, str):
names = [value]
else:
names = list(value)
modes = []
for name in names:
mode = self._enabled_mode_name(name)
if mode not in modes:
modes.append(mode)
self._mask = modes
@staticmethod
def _enabled_mode_name(mode):
if not isinstance(mode, str):
raise TypeError(f"a snap mode must be a string, got {type(mode).__name__}")
if mode in _UNSUPPORTED_MODES:
raise NotImplementedError(
f"Snapper: the {mode!r} snap mode needs a live cursor or an "
"edge/face extension solver and is not implemented natively; "
"supported modes are "
+ ", ".join(_SUPPORTED_MODES)
)
if mode not in _SUPPORTED_MODES:
raise ValueError(
f"Snapper: unknown snap mode {mode!r}; supported modes are "
+ ", ".join(_SUPPORTED_MODES)
)
return mode
def mode_enabled(self, mode):
return mode in self._mask
def isEnabled(self, snap=None):
if snap is None:
return bool(self._enabled)
if snap in _UNSUPPORTED_MODES or snap not in _SUPPORTED_MODES:
return False
return snap in self._mask
def set_enabled(self, enabled=True):
self._enabled = bool(enabled)
return self._enabled
def toggle_enabled(self):
return self.set_enabled(not self._enabled)
setEnabled = set_enabled
toggleEnabled = toggle_enabled
def toggle_snap(self, snap, set_to=None):
if snap in _UNSUPPORTED_MODES:
if set_to is False:
return False
raise NotImplementedError(
f"Snapper: the {snap!r} snap mode needs a live cursor or an "
"edge/face extension solver and is not implemented natively"
)
self._enabled_mode_name(snap)
if set_to is None:
enabled = snap not in self._mask
else:
enabled = bool(set_to)
if enabled:
if snap not in self._mask:
self._mask.append(snap)
else:
if snap in self._mask:
self._mask.remove(snap)
return enabled
toggle = toggle_snap
def set_mode(self, snap, enabled=True):
return self.toggle_snap(snap, bool(enabled))
setMode = set_mode
def enable(self, snap):
return self.set_mode(snap, True)
def disable(self, snap):
return self.set_mode(snap, False)
def active_snaps(self):
return list(self.mask)
@staticmethod
def supported_modes():
return supported_modes()
@staticmethod
def unsupported_modes():
return unsupported_modes()
@property
def workplane(self):
base = self._base_workplane
if base is None:
base = _stage_module().Workplane.world()
self._base_workplane = base
if not self._angle:
return base
stage = _stage_module()
cos = math.cos(self._angle)
sin = math.sin(self._angle)
u = base.u
v = base.v
ru = (
u[0] * cos + v[0] * sin,
u[1] * cos + v[1] * sin,
u[2] * cos + v[2] * sin,
)
rv = (
-u[0] * sin + v[0] * cos,
-u[1] * sin + v[1] * cos,
-u[2] * sin + v[2] * cos,
)
return stage.Workplane(base.origin, ru, rv, base.kind)
def setWorkplane(self, workplane):
if not all(hasattr(workplane, name) for name in ("origin", "u", "v")):
raise TypeError("setWorkplane expects a ferrocad_stage.Workplane")
self._base_workplane = workplane
self._angle = 0.0
return self.workplane
set_workplane = setWorkplane
@property
def angle(self):
return math.degrees(self._angle)
@property
def context(self):
stage = _stage_module()
grid_on = bool(self.grid) and "Grid" in self._mask
return stage.SnapContext(
self.workplane,
self._minor if grid_on else 0.0,
self._major if grid_on else 0.0,
)
@context.setter
def context(self, value):
if not all(hasattr(value, name) for name in ("workplane", "minor", "major")):
raise TypeError("context expects a ferrocad_stage.SnapContext")
self._base_workplane = value.workplane
self._angle = 0.0
self._minor = float(value.minor)
self._major = float(value.major)
self.grid = self._minor > 0.0
@property
def snap_context(self):
return self.context
def setGrid(self, enabled=True):
self.grid = bool(enabled)
return self.grid
def toggleGrid(self):
self.grid = not self.grid
return self.grid
def setAngle(self, angle):
if angle is None:
self._angle = 0.0
return self.workplane
value = float(angle)
if abs(value) > 2.0 * math.pi:
value = math.radians(value)
self._angle = value
return self.workplane
def snap(self, point, candidates=None):
stage = _stage_module()
world = _triple(point)
allowed = self._allowed_kinds(stage)
if candidates is None:
candidates = ()
elif hasattr(candidates, "kind"):
candidates = (candidates,)
filtered = []
for candidate in candidates:
kind = getattr(candidate, "kind", None)
if kind is None:
raise TypeError(
"snap candidates must be ferrocad_stage.SnapCandidate values"
)
if kind in allowed:
filtered.append(candidate)
if self.mode_enabled("Vertex") or self.mode_enabled("Endpoint"):
filtered.extend(
stage.SnapCandidate(point, stage.SnapKind.Vertex)
for point in self.holdPoints
)
tolerance = 0.0 if self.affinity is None else float(self.affinity)
result = self.context.snap_point(world, filtered, tolerance)
self.snapInfo = result
return result.point
def _allowed_kinds(self, stage):
kinds = []
for mode, kind_name in _MODE_KINDS.items():
if mode in self._mask:
kind = getattr(stage.SnapKind, kind_name)
if kind not in kinds:
kinds.append(kind)
return kinds
def getPoint(self, callback, *args, on_cancel=None, on_finish=None):
if not callable(callback):
raise TypeError("Snapper.getPoint needs a callable callback")
if on_cancel is not None and not callable(on_cancel):
raise TypeError("Snapper.getPoint on_cancel must be callable")
if on_finish is not None and not callable(on_finish):
raise TypeError("Snapper.getPoint on_finish must be callable")
if self._pending is not None:
print(
"FreeCADGui.Snapper: a point request was already pending; "
"replacing it with the new request",
file=sys.stderr,
)
self._pending = _PointRequest(callback, args, on_cancel, on_finish)
self.running = True
return None
def _take_pending(self):
pending, self._pending = self._pending, None
self.running = False
return pending
def _drop_pending(self):
return self._take_pending() is not None
def off(self):
pending = self._take_pending()
self.selectMode = False
self.unconstrain()
self.snapInfo = None
if pending is not None and pending.on_cancel is not None:
return pending.on_cancel()
return None
def setSelectMode(self, enabled):
self.selectMode = bool(enabled)
def _axis_vector(self, axis):
if isinstance(axis, str):
key = axis.lower()
workplane = self.workplane
if key == "x":
return _triple(workplane.u)
if key == "y":
return _triple(workplane.v)
if key == "z":
return _triple(workplane.n)
raise ValueError(
"a constraint axis must be 'x', 'y', 'z' or a vector, "
f"got {axis!r}"
)
return _unit(axis)
def _closest_axis(self, delta):
workplane = self.workplane
axes = (_triple(workplane.u), _triple(workplane.v), _triple(workplane.n))
return max(axes, key=lambda axis: abs(_dot(delta, axis)))
def constrain(self, point, basepoint=None, axis=None):
world = _triple(point)
base = self.basepoint if basepoint is None else _triple(basepoint)
if base is None:
base = world
if axis is None:
axis_vector = self.constraintAxis
if axis_vector is None:
delta = (
world[0] - base[0],
world[1] - base[1],
world[2] - base[2],
)
axis_vector = self._closest_axis(delta)
else:
axis_vector = self._axis_vector(axis)
axis_vector = _unit(axis_vector)
delta = (world[0] - base[0], world[1] - base[1], world[2] - base[2])
length = _dot(delta, axis_vector)
constrained = (
base[0] + axis_vector[0] * length,
base[1] + axis_vector[1] * length,
base[2] + axis_vector[2] * length,
)
self.basepoint = base
self.constraintAxis = axis_vector
return constrained
def unconstrain(self):
self.basepoint = None
self.constraintAxis = None
def setPointConstraintProvider(self, provider):
self.pointConstraintProvider = provider
def clearPointConstraintProvider(self, provider=None):
if provider is None or self.pointConstraintProvider is provider:
self.pointConstraintProvider = None
def setTrackers(self, update_grid=True):
if update_grid:
self.grid = bool(self.grid)
return self.context
def restack(self):
raise NotImplementedError(
"Snapper.restack(): FerroCAD has no Coin snap tracker to restack"
)
def addHoldPoint(self, point=None):
if point is None:
if self.snapInfo is None:
raise ValueError(
"Snapper.addHoldPoint needs a point or a previous snap"
)
point = self.snapInfo.point
world = _triple(point)
if world not in self.holdPoints:
self.holdPoints.append(world)
return True
def show(self):
return self.setGrid(True)
def hide(self):
return self.setGrid(False)
def cycleSnapObject(self, *_args, **_kwargs):
raise NotImplementedError(
"Snapper.cycleSnapObject(): FerroCAD has no hovering cursor to "
"cycle snap objects through; pass explicit SnapCandidates to snap()"
)
def get_snap_toolbar(self):
return list(SNAP_TOOLBAR)
def reset(self):
self._mask = list(_SUPPORTED_MODES)
self.selectMode = False
self.affinity = 1.0
self.grid = True
self.snapInfo = None
self.holdPoints = []
self.pointConstraintProvider = None
self.constrain_reset()
self._enabled = True
self._pending = None
self.running = False
self._minor = 1.0
self._major = 10.0
self._base_workplane = None
self._angle = 0.0
self.hint = ""
def constrain_reset(self):
self.unconstrain()
Snapper = _Snapper()
def pick(point):
pending = Snapper._take_pending()
snapped = Snapper.snap(point)
if pending is not None:
pending.invoke(snapped)
return snapped
def escape():
had_pending = Snapper._pending is not None
Snapper.off()
return had_pending
def finish():
pending = Snapper._take_pending()
if pending is None or pending.on_finish is None:
return False
return pending.on_finish()
class _DraftToolBar:
def __init__(self):
self.ui = self
self.mouse = True
self.sourceCmd = None
self.isTaskOn = False
self.isConstructionMode = False
self.autogroup = None
self.globalMode = False
self.relativeMode = True
self.wplabel = None
self.textValue = None
self.makeFaceMode = True
self.continueCmd = False
self.loadedPreferences = False
self.tray = None
self.taskUi = None
self.panel = None
self.panelName = None
self.new_point = None
self.last_point = None
self.mask = None
self.pointcallback = None
def Activated(self):
self.isTaskOn = True
Snapper.ui = self
return None
def Deactivated(self):
self.isTaskOn = False
Snapper.clearPointConstraintProvider(self)
command = self.sourceCmd
self._finish_command(command)
self.sourceCmd = None
return None
def offUi(self):
Snapper.clearPointConstraintProvider(self)
self.sourceCmd = None
self.isTaskOn = False
self.pointcallback = None
self.textValue = None
self.mask = None
return None
def _finish_command(self, command, cont=False):
finish = getattr(command, "finish", None)
if not callable(finish):
return False
try:
finish(cont=cont)
except TypeError:
finish()
return True
def validatePoint(self, point=None):
if point is None:
return True
world = _triple(point)
if Snapper.basepoint is not None or Snapper.constraintAxis is not None:
world = Snapper.constrain(world)
provider = Snapper.pointConstraintProvider
if provider is not None:
has = getattr(provider, "has_point_constraints", None)
if not callable(has) or has():
constrained = provider.constrain_point(world, Snapper.basepoint)
if constrained is not None:
world = _triple(constrained)
self.new_point = world
return world
def escape(self):
Snapper.off()
command = self.sourceCmd
if command is not None:
self._finish_command(command, cont=False)
self.sourceCmd = None
self.isTaskOn = False
return None
def setStyleButton(self, *_args, **_kwargs):
raise NotImplementedError(
"draftToolBar.setStyleButton(): FerroCAD's headless task panel has "
"no Qt style button; set the Draft style through FerroCAD.Grid/"
"the style parameters instead"
)
def setAutoGroup(self, value=None):
self.autogroup = None if value is None else value
return self.autogroup
draftToolBar = _DraftToolBar()
class _HintManager:
def __init__(self):
self.hints = ()
self.hint = ""
def show(self, *hints):
self.hints = tuple(hints)
self.hint = "\n".join(str(hint) for hint in hints)
FreeCADGui.draft.hint = self.hint
return self.hint
def hide(self):
self.hints = ()
self.hint = ""
FreeCADGui.draft.hint = ""
return None
@property
def last(self):
return self.hints[-1] if self.hints else None
@property
def last_hint(self):
return self.last
HintManager = _HintManager()
class InputHint:
__slots__ = ("text", "args")
def __init__(self, text, *args):
self.text = text
self.args = tuple(args)
def __eq__(self, other):
if not isinstance(other, InputHint):
return NotImplemented
return (self.text, self.args) == (other.text, other.args)
def __repr__(self):
if not self.args:
return f"InputHint({self.text!r})"
arguments = ", ".join(repr(arg) for arg in self.args)
return f"InputHint({self.text!r}, {arguments})"
class _UserInputSentinel:
__slots__ = ("name",)
def __init__(self, name):
self.name = name
def __repr__(self):
return f"UserInput.{self.name}"
class UserInput:
MouseLeft = _UserInputSentinel("MouseLeft")
MouseMiddle = _UserInputSentinel("MouseMiddle")
MouseRight = _UserInputSentinel("MouseRight")
MouseMove = _UserInputSentinel("MouseMove")
KeyEscape = _UserInputSentinel("KeyEscape")
KeyEnter = _UserInputSentinel("KeyEnter")
KeyDelete = _UserInputSentinel("KeyDelete")
class _SnapCommand:
mode = ""
menu = ""
tooltip = ""
def __init__(self, mode, menu, tooltip):
self.mode = mode
self.menu = menu
self.tooltip = tooltip
def GetResources(self):
return {
"Pixmap": _COMMAND_IDS[self.mode],
"MenuText": self.menu,
"FerroCAD_Short": self.mode,
"ToolTip": self.tooltip,
"CmdType": "NoTransaction",
"Checkable": True,
"FerroCAD_Surface": "snap",
"FerroCAD_Parent": _SNAP_LOCK_ID,
}
def IsActive(self):
return Snapper.isEnabled()
def IsChecked(self):
return Snapper.mode_enabled(self.mode)
def Activated(self, status=None):
if status is None:
return Snapper.toggle_snap(self.mode)
return Snapper.toggle_snap(self.mode, bool(status))
def __repr__(self):
return f"<{_COMMAND_IDS[self.mode]} mode={self.mode!r}>"
class _SnapLockCommand:
def GetResources(self):
return {
"Pixmap": _SNAP_LOCK_ID,
"MenuText": "Snap Lock",
"ToolTip": "Turn snapping on or off; the snap modes keep their own state",
"CmdType": "NoTransaction",
"Checkable": True,
"FerroCAD_Surface": "snap",
}
def IsActive(self):
return True
def IsChecked(self):
return Snapper.isEnabled()
def Activated(self, status=None):
if status is None:
return Snapper.toggle_enabled()
return Snapper.set_enabled(bool(status))
def __repr__(self):
return f"<{_SNAP_LOCK_ID} enabled={Snapper.isEnabled()}>"
def _command_specs():
return (
("Grid", "Snap Grid", "Snaps to the intersections of grid lines"),
("Endpoint", "Snap Endpoint", "Snaps to the endpoints of edges"),
("Midpoint", "Snap Midpoint", "Snaps to the midpoint of edges"),
("Center", "Snap Center", "Snaps to the centre of a face or arc"),
("Origin", "Snap Origin", "Snaps to the workplane origin"),
("Vertex", "Snap Vertex", "Snaps to a topological vertex"),
)
def _register_commands():
registered = set(FreeCADGui.listCommands())
if _SNAP_LOCK_ID not in registered:
FreeCADGui.addCommand(_SNAP_LOCK_ID, _SnapLockCommand())
for mode, menu, tooltip in _command_specs():
command_id = _COMMAND_IDS[mode]
if command_id in registered:
continue
FreeCADGui.addCommand(command_id, _SnapCommand(mode, menu, tooltip))
_register_commands()
def _install():
FreeCADGui.draft = sys.modules[__name__]
Snapper.ui = draftToolBar
draftToolBar.ui = draftToolBar
FreeCADGui.Snapper = Snapper
FreeCADGui.draftToolBar = draftToolBar
FreeCADGui.HintManager = HintManager
FreeCADGui.InputHint = InputHint
FreeCADGui.UserInput = UserInput
_install()