Ready for V1.1.0 to pypi

Tested backwards compatibility with V1.0.0 demo, added comments to minimal and customised V1.1.0 demos

Author: G1OJS

demo_V1.0.0_test.py

@@ -0,0 +1,22 @@
+# for backwards compatibility with V1.0.0, this is the existing demo code
+
+from xyz_canvas.canvas import define_points
+
+
+def on_complete(lines):
+    print("Points created are:")
+    for l in lines:
+        print(l)
+
+demo_3D_builder = define_points(on_complete_cb = on_complete,
+                               xlim =[0,10], ylim =[-20,30], zlim=[-3,5],
+                               xlabel="x", ylabel="y", zlabel="z")
+
+# up to here....
+
+# - Moved `plt.show()` out of `__init__` to allow users more control over plot display timing.
+# - Users now must call `.show()`  explicitly when ready to display.
+
+demo_3D_builder.plt.show()
+
+# also note that on_complete_cb is no longer used, and 'lines' in the example above should have been 'points'

demo_minimal.py renamed to demo_V1.1.0_minimal.py

@@ -10,5 +10,8 @@
 # showing the plot
 demo.plt.show()
 
+# note that this is so minimal that all it does is display;
+# the resulting points are not used here.
+
 print("Demo finished ...")
 

demo_with_customisation.py renamed to demo_V1.1.0_with_customisation.py

@@ -5,6 +5,9 @@
 # callback examples
 
 def on_click(canvas, xyz, pt_index):
+    # add more of your own code here - xyz is the 3D point clicked, and
+    # pt_index is None if there's no defined point associated, otherwise
+    # it's the index (i.e. 'point number' of the points created
     if (pt_index is not None):
         print(f"Clicked on point {pt_index} at {canvas.points_xyz[pt_index]}")
         if(len(canvas.points_xyz) >3):
@@ -14,6 +17,9 @@ def on_click(canvas, xyz, pt_index):
         print(f"Clicked at {xyz}")
 
 def on_move(canvas, xyz, selectable_pt_index, selected_pt_index):
+    # add more of your own code here - xyz is the 3D point of the mouse pointer,
+    # selectable_pt_index is the point index of points 'hovered over', or None
+    # selected_pt_index is the point index of any point being 'carried', or None
     if (selectable_pt_index is not None):
         print(f"Moved to {xyz} near point {selectable_pt_index}" )
     if (selected_pt_index is not None):

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xyz_canvas"
-version = "1.0.0"
+version = "1.1.0"
 license = "MIT"
 
 authors = [

xyz_canvas/canvas.py

@@ -35,11 +35,9 @@ def _interleave(ends):
 
 class xyz_canvas:
 
-    def __init__(self,
-                 xlim =[0,1], ylim =[0,1], zlim=[0,1],
-                 xlabel="x", ylabel="y", zlabel="z",
-                 on_click_cb = None,
-                 on_move_cb = None
+    def __init__(self, *args, xlim =[0,10], ylim =[-20,30], zlim=[-3,5],
+                               xlabel="x", ylabel="y", zlabel="z",
+                               on_click_cb = None, on_move_cb = None, **kwargs
                  ):
         self.plt = plt
         self.fig = plt.figure()
@@ -93,13 +91,6 @@ def redraw(self, showframe_xyz=None):
             x,y,z = xyz[0],xyz[1],xyz[2]
             self.ax.text(x,y,z,f"  ({x:.3f}, {y:.3f}, {z:.3f})", size = 'small')
 
-    def on_button_press(self,action):
-        if action == 'clear':
-            self.init_canvas()
-        elif action == 'save':
-            self.on_complete_cb(self.points_xyz)
-        elif action == 'exit':
-            plt.close()
 
     def on_pointer_click(self, xyz, ep_idx):
         # If we click whilst moving a point, drop it.
@@ -236,3 +227,18 @@ def _in_axes_range(self, p):
         y_in = self.ax.get_ylim()[0] <= p[1] <= self.ax.get_ylim()[1]
         z_in = self.ax.get_zlim()[0] <= p[2] <= self.ax.get_zlim()[1]
         return (x_in and y_in and z_in)
+
+
+
+# Keep old name as an alias with deprecation warning
+class define_points(xyz_canvas):
+    def __init__(self, *args, on_complete_cb=None, **kwargs):
+        warnings.warn(
+            "define_points is deprecated and will be removed in a future version. "
+            "Please use NewClassName instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        if on_complete_cb is not None:
+            warnings.warn("on_complete_cb is no longer used and will be ignored.", DeprecationWarning)
+        super().__init__(*args, **kwargs)