From a89f07c441588d5e6003e539811e72e63a958c04 Mon Sep 17 00:00:00 2001
From: jan <jan@orange.mpxd.net>
Date: Sat, 7 Mar 2026 23:36:14 -0800
Subject: [PATCH] [Port] add describe() for logging

---
 masque/ports.py | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/masque/ports.py b/masque/ports.py
index 04ab061..4be208d 100644
--- a/masque/ports.py
+++ b/masque/ports.py
@@ -143,6 +143,33 @@ class Port(PivotableImpl, PositionableImpl, Mirrorable, Flippable, Copyable):
         self.rotation = rotation
         return self
 
+    def describe(self) -> str:
+        """
+        Returns a human-readable description of the port's state including cardinal directions.
+        """
+        deg = numpy.rad2deg(self.rotation) if self.rotation is not None else "any"
+
+        cardinal = ""
+        travel_dir = ""
+
+        if self.rotation is not None:
+            dirs = {0: "East (+x)", 90: "North (+y)", 180: "West (-x)", 270: "South (-y)"}
+            # normalize to [0, 360)
+            deg_norm = deg % 360
+
+            # Find closest cardinal
+            closest = min(dirs.keys(), key=lambda x: abs((deg_norm - x + 180) % 360 - 180))
+            if numpy.isclose((deg_norm - closest + 180) % 360 - 180, 0, atol=1e-3):
+                cardinal = f" ({dirs[closest]})"
+
+            # Travel direction (rotation + 180)
+            t_deg = (deg_norm + 180) % 360
+            closest_t = min(dirs.keys(), key=lambda x: abs((t_deg - x + 180) % 360 - 180))
+            if numpy.isclose((t_deg - closest_t + 180) % 360 - 180, 0, atol=1e-3):
+                travel_dir = f" (Travel -> {dirs[closest_t]})"
+
+        return f"pos=({self.x:g}, {self.y:g}), rot={deg:g}{cardinal}{travel_dir}"
+
     def __repr__(self) -> str:
         if self.rotation is None:
             rot = 'any'
@@ -210,11 +237,11 @@ class PortList(metaclass=ABCMeta):
 
     def _log_port_update(self, name: str) -> None:
         """ Log the current state of the named port """
-        port_logger.info("Port %s: %s", name, self.ports[name])
+        port_logger.debug("Port %s: %s", name, self.ports[name].describe())
 
     def _log_port_removal(self, name: str) -> None:
         """ Log that the named port has been removed """
-        port_logger.info("Port %s: removed", name)
+        port_logger.debug("Port %s: removed", name)
 
     def _log_bulk_update(self, label: str) -> None:
         """ Log all current ports at DEBUG level """