squarenet 0.2.1__tar.gz → 0.2.2__tar.gz

squarenet-0.2.2/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: squarenet
+Version: 0.2.2
+Summary: Sparse local operations for point clouds in any dimension.
+Author-email: ArmanddeCacqueray <armanddecacqueray@sfr.fr>
+Project-URL: Homepage, https://github.com/ArmanddeCacqueray/SquareNet
+Project-URL: Documentation, https://squarenet.readthedocs.io
+Project-URL: PyPI, https://pypi.org/project/squarenet/
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Provides-Extra: demo
+Requires-Dist: shapely; extra == "demo"
+Provides-Extra: zsquare
+Requires-Dist: tensorly; extra == "zsquare"
+Dynamic: license-file
+
+-----
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ArmanddeCacqueray/SquareNet/blob/main/exemples/00_getting_started.ipynb)
+[![PyPI version](https://img.shields.io/pypi/v/squarenet.svg)](https://pypi.org/project/squarenet/)
+[![Documentation Status](https://readthedocs.org/projects/squarenet/badge/?version=latest)](https://squarenet.readthedocs.io/en/latest/)
+<p align="center">
+  <img src="plots/logo.png" width="200" alt="Project visualization">
+</p>
+
+❒  SquareNet
+
+SquareNet maps unstructured **point clouds** to structured grids through a **bijective transformation**. It replaces expensive spatial queries (k-NN, radius search) with super fast **sliding window** operations. Think of it as a powerful alternative to kd-trees, voxelization, rasterization and neighborhood graphs.
+✔ Works in any dimension
+✔ Handles non-convex geometries
+✔ Scales to millions of points (fast processing)
+
+
+-----
+
+## 🚀 Why SquareNet?
+
+  * **Speed:** $O(N)$ local operations via vectorized sliding windows.
+  * **Memory:** Contiguous memory access instead of irregular spatial lookups.
+  * **Simplicity:** Pure NumPy-based logic, no heavy spatial dependencies.
+
+## 📦 Installation
+
+```bash
+pip install squarenet
+```
+
+## 🧠 Quick Start 
+-> exemples/00_getting_started.ipynb
+
+```python
+from squarenet import SquareNet
+import numpy as np
+
+# Initialize and Fit
+N = 5*11*7*13
+d = 4
+points = np.random.rand(N, d)
+
+IJKL = (5, 11, 7, 13)
+sqnet = SquareNet(IJ_=IJKL) # Define grid dimensions, here 4D
+sqnet.fit(points)
+
+# Map any property of the points to the grid e.g. the norm, could be anything else
+Xpts = np.linalg.norm(points, axis = 1) #(N, *C)
+Xmap = sqnet.map(Xpts) #(5, 11, 7, 13, *C)
+Xrec = sqnet.invert_map(Xmap)   #(N, *C) 
+```
+## Compute Local Views 
+```python
+# views enhance Xpts with a view in a rectangular neighborhood 
+# (in the grid) with radius *wr and size *ws = 2wr+1
+Xview = sqnet.views(Xpts, wr=5, invert_map = True) #(N, *C, *ws)
+```
+
+## 🗺️ Visualizing the Mapping
+
+You can use the built-in checkerboard to verify neighborhood preservation:
+
+```python
+sqnet = SquareNet(IJ_=(400, 400))
+sqnet.fit("france") #require !pip install shapely
+sqnet.checkerboard()
+```
+
+## 📈 Key Applications
+
+  * **Point Cloud Processing:** Fast local feature aggregation.
+  * **Kernel Methods:** Efficient sparse approximation of large kernels.
+  * **Deep Learning:** Pre-structuring irregular data for CNN/Transformer inputs.
+
+<p align="center">
+  <img src="plots/packing.png" width="200" alt="Packing">
+</p>
+-----
+
+**License:** MIT | **Author:** [ArmanddeCacqueray](mailto:armanddecacqueray@sfr.fr)

squarenet-0.2.2/README.md

@@ -0,0 +1,80 @@
+-----
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ArmanddeCacqueray/SquareNet/blob/main/exemples/00_getting_started.ipynb)
+[![PyPI version](https://img.shields.io/pypi/v/squarenet.svg)](https://pypi.org/project/squarenet/)
+[![Documentation Status](https://readthedocs.org/projects/squarenet/badge/?version=latest)](https://squarenet.readthedocs.io/en/latest/)
+<p align="center">
+  <img src="plots/logo.png" width="200" alt="Project visualization">
+</p>
+
+❒  SquareNet
+
+SquareNet maps unstructured **point clouds** to structured grids through a **bijective transformation**. It replaces expensive spatial queries (k-NN, radius search) with super fast **sliding window** operations. Think of it as a powerful alternative to kd-trees, voxelization, rasterization and neighborhood graphs.
+✔ Works in any dimension
+✔ Handles non-convex geometries
+✔ Scales to millions of points (fast processing)
+
+
+-----
+
+## 🚀 Why SquareNet?
+
+  * **Speed:** $O(N)$ local operations via vectorized sliding windows.
+  * **Memory:** Contiguous memory access instead of irregular spatial lookups.
+  * **Simplicity:** Pure NumPy-based logic, no heavy spatial dependencies.
+
+## 📦 Installation
+
+```bash
+pip install squarenet
+```
+
+## 🧠 Quick Start 
+-> exemples/00_getting_started.ipynb
+
+```python
+from squarenet import SquareNet
+import numpy as np
+
+# Initialize and Fit
+N = 5*11*7*13
+d = 4
+points = np.random.rand(N, d)
+
+IJKL = (5, 11, 7, 13)
+sqnet = SquareNet(IJ_=IJKL) # Define grid dimensions, here 4D
+sqnet.fit(points)
+
+# Map any property of the points to the grid e.g. the norm, could be anything else
+Xpts = np.linalg.norm(points, axis = 1) #(N, *C)
+Xmap = sqnet.map(Xpts) #(5, 11, 7, 13, *C)
+Xrec = sqnet.invert_map(Xmap)   #(N, *C) 
+```
+## Compute Local Views 
+```python
+# views enhance Xpts with a view in a rectangular neighborhood 
+# (in the grid) with radius *wr and size *ws = 2wr+1
+Xview = sqnet.views(Xpts, wr=5, invert_map = True) #(N, *C, *ws)
+```
+
+## 🗺️ Visualizing the Mapping
+
+You can use the built-in checkerboard to verify neighborhood preservation:
+
+```python
+sqnet = SquareNet(IJ_=(400, 400))
+sqnet.fit("france") #require !pip install shapely
+sqnet.checkerboard()
+```
+
+## 📈 Key Applications
+
+  * **Point Cloud Processing:** Fast local feature aggregation.
+  * **Kernel Methods:** Efficient sparse approximation of large kernels.
+  * **Deep Learning:** Pre-structuring irregular data for CNN/Transformer inputs.
+
+<p align="center">
+  <img src="plots/packing.png" width="200" alt="Packing">
+</p>
+-----
+
+**License:** MIT | **Author:** [ArmanddeCacqueray](mailto:armanddecacqueray@sfr.fr)

{squarenet-0.2.1 → squarenet-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "squarenet"
-version = "0.2.1"
+version = "0.2.2"
 description = "Sparse local operations for point clouds in any dimension."
 authors = [{ name = "ArmanddeCacqueray", email = "armanddecacqueray@sfr.fr" }]
 readme = "README.md"
@@ -14,13 +14,22 @@ dependencies = [
     "matplotlib"
 ]
 
+[project.urls]
+Homepage = "https://github.com/ArmanddeCacqueray/SquareNet"
+Documentation = "https://squarenet.readthedocs.io"
+PyPI = "https://pypi.org/project/squarenet/"
+
 [project.optional-dependencies]
 demo = [
     "shapely"
 ]
+Zsquare = [
+    "tensorly"
+]
+
 
 [tool.setuptools.packages.find]
 where = ["src"]
 
 [tool.setuptools.package-data]
-"squarenet" = ["data/*.wkb"]
+"squarenet" = ["data/*.wkb"]

squarenet-0.2.2/src/squarenet/__init__.py

@@ -0,0 +1,4 @@
+from .squarenet import SquareNet
+from .utils import Potential,  breakpoint
+__all__ = ["squarenet"]
+__version__ = "0.1.0"

squarenet-0.2.2/src/squarenet/boards.py

@@ -0,0 +1,71 @@
+import numpy as np
+import matplotlib.pyplot as plt
+from mpl_toolkits.mplot3d.art3d import Poly3DCollection
+
+def checkerboard(grid, scale):
+    """Split a grid into two sets of blocks following a checkerboard pattern."""
+    ni, nj = grid.shape[:2]
+    d = grid.shape[-1]
+    hi, hj = ni // scale, nj // scale
+
+    # Crop to ensure clean divisibility
+    grid = grid[:hi * scale, :hj * scale]
+
+    # Reshape and transpose into a block structure
+    blocks = grid.reshape(scale, hi, scale, hj, d)
+    blocks = blocks.transpose(0, 2, 1, 3, 4)
+
+    # Flatten into blocks for easy masking
+    flat_blocks = blocks.reshape(scale, scale, hi * hj, d)
+
+    # Generate checkerboard mask
+    ii, jj = np.indices((scale, scale))
+    mask = (ii % 2) == (jj % 2)
+
+    return flat_blocks[mask], flat_blocks[~mask]
+
+def checkerboard2D(grid, scale=[2, 4, 8, 16], ax=None, colors=("lightgrey", "blue"), s=1, alpha=0.7):
+    """Visualize different checkerboard scales on a 2D/3D point grid."""
+    # 1. Handle multiple scales
+    if isinstance(scale, list):
+        ns = int(np.sqrt(len(scale)))
+        fig, axes = plt.subplots(ns, ns, figsize=(10, 10))
+        for a, sc in zip(axes.flat, scale):
+            checkerboard2D(grid, scale=sc, ax=a, colors=colors, s=s, alpha=alpha)
+        return axes
+
+    # 2. Base case: single scale
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6, 6))
+    
+    # Use the checkerboard function to get the two sets of points
+    set1, set2 = checkerboard(grid, scale)
+
+    # Plot both sets (set1 are all 'blue' blocks, set2 are all 'lightgrey' blocks)
+    for points, color in zip([set1, set2], colors):
+        # points shape: (num_blocks, points_per_block, dims) -> flat for scatter
+        pts_flat = points.reshape(-1, grid.shape[-1])
+        ax.scatter(*(pts_flat[:, i] for i in range(pts_flat.shape[-1])), 
+                   c=color, s=s, alpha=alpha, edgecolors='none')
+
+    ax.set_title(f"Scale: {scale}")
+    ax.axis("off")
+    return ax
+
+def checkerboard3D(grid_3d, scale=8, ax = None, colors=("lightgrey", "blue"), s=3, alpha=1):
+    """Visualize different checkerboard scales on the surface of a 3D point grid."""
+    if ax is None:
+        fig = plt.figure(figsize=(10, 10))
+        ax = fig.add_subplot(111, projection='3d')
+
+    faces = [
+        grid_3d[-1, :, :], #grid_3d[0, :, :],
+        grid_3d[:, 0, :], #grid_3d[:, -1, :],
+        grid_3d[:, :, -1], #grid_3d[:, :, 0]
+    ]
+
+    for face in faces:
+        checkerboard2D(face, scale=scale, ax=ax, colors = colors, s=s, alpha=alpha)
+
+    ax.set_box_aspect([1, 1, 1])
+    plt.show()

squarenet-0.2.2/src/squarenet/core.py

@@ -0,0 +1,154 @@
+import numpy as np
+
+""""
+=============================================
+=============================================
+PSEUDO-CODE: convert unstructured point cloud (N, D) 
+to a grid (N1, ..., ND, D) by iteratively sorting 
+the d-est heuristic along the d-est axis
+
+We can see the grid as D iterators on the points 
+such that axis-d iterator maps  the point 
+P(n ~ n1...nd...nD) to the "next" point
+Pnext(n ~ n1...nd+1...nD). Let call it Pnext(n, d)
+
+We can select D euclidian heuristics 
+H(d): (x, y, z,...) -> value which we want to 
+be increasing along the d-est axis of the grid
+It turns out that H(0) = x, H(1) = y,.... is
+already a pretty good heuristic.
+
+So the goal is simply to ensure that all
+heuristics are sorted along the grid, in the
+sense that for all point P(n) and axis d,
+H(d)(P(n)) <= H(d)(Pnext(n, d))
+
+We can compute a grid disorder parameter which is
+just the counts of all P, Pnext which breaks this 
+inequality
+=============================================
+Sort_increasing is then pretty simple:
+For learning step in (1, Max_iter = 100)
+    For d in (1, D):
+        sort heuristic d along axis d.
+    Check disorder
+    If disorder = 0, we are done !
+=============================================
+=============================================
+"""
+
+def sort_increasing(gridmap, heuristics, max_iter=100):
+    """
+    Args: 
+        -gridmap (np.array of ints):
+        an initial gridmap such that cloud_features[gridmap] 
+        write any feature (N, *C) of the point-cloud (N, D) 
+        on a grid (N1, ..., ND, *C)
+
+        -max_iter (int):
+        last step after which algorithm shall stop
+        even if it hasn't converged yet
+    Returns:
+        -gridmap
+        sorted gridmap such that cloud_features[gridmap]
+        now write the feature on a spatially coherent grid
+        -learningcurve (list of values):
+        track the performance of the optimisation process.
+        should converge to 0
+    """
+    g = gridmap.copy()
+    learning_curve = []
+
+    #loop[0]: index to heuristic 0
+    #loop[d+1]: heuristic d to heuristic d+1
+    #back_to_id: heuristic D-1 to index
+    loop, back_to_id = loop_boost(heuristics)
+    
+    for _ in range(max_iter):
+         # --- 1. Check for convergence ---
+        disorder = 0
+        for d, heuristic in enumerate(loop):
+            g = heuristic[g]
+            
+            # Efficient disorder check: H(d)(P) > H(d)(Pnext)
+            diff = np.diff(g, axis=d)
+            disorder += np.sum(diff < 0)
+        
+        g = back_to_id[g]
+
+        learning_curve.append(disorder)           
+        if disorder == 0:
+            break
+
+        # --- 2. Sorting Phase ---
+        for d, heuristic in enumerate(loop):
+            g = heuristic[g]
+            g.sort(axis = d)
+            
+        g = back_to_id[g]
+
+    # last cleanup:
+    gridmap = np.ascontiguousarray(g)
+    return gridmap, learning_curve
+
+# ============================================
+# ============================================
+# Heuristics
+# ============================================
+# ============================================
+def carthesian_heuristics(points):
+    return points
+
+# ============================================
+# ============================================
+# Boosters
+# ============================================
+# ============================================
+def integer_boost(heuristics):
+    """
+    Booster: Convert heuristics to integer 
+    to boost sort_increasing function
+
+    Args:
+        - heuristics (np.ndarray) (N,D): heuristics computed on the point cloud
+
+    Returns:
+        - h_int (list of np.uint32 arrays): heuristics as integers
+    """
+    N, D = heuristics.shape
+    h_int = []
+    for d in range(D):
+        order = np.argsort(heuristics[:, d])      
+        ranks = np.empty(N, dtype=np.int32)
+        ranks[order] = np.arange(N)
+        h_int.append(ranks)
+    return h_int
+
+def loop_boost(heuristics):
+    """
+    Booster: make looping over heuristics a bit faster
+
+    Args:
+        - heuristics (np.ndarray) (N,D): heuristics computed on the point cloud
+    Return:
+        - loop (...): list of permutations such that 
+        loop[d](h_int[d][n]) = h_int[d+1][n]
+        - back_to_id (...): permutation such that 
+        back_to_id(h_int[-1][n]) = n 
+    """
+    int_boost = integer_boost(heuristics)
+    N = len(int_boost[0])
+    identity = np.arange(N, dtype=np.int32)
+    #start the loop
+    h_int =  [identity] + int_boost
+    #close the loop
+    h_int_plus = int_boost + [identity]
+    loop = []
+
+    for h, hplus in zip(h_int, h_int_plus):
+        sigma = np.zeros(N, dtype=np.int32)
+        sigma[h] = hplus
+        loop.append(np.ascontiguousarray(sigma))
+        
+    loop, back_to_id = loop[:-1], loop[-1]
+    return loop, back_to_id

squarenet-0.2.2/src/squarenet/squarenet.py

@@ -0,0 +1,230 @@
+import numpy as np
+from .core import sort_increasing, carthesian_heuristics
+from .boards import checkerboard, checkerboard2D, checkerboard3D
+from .views import localview, lazylocalview
+from .utils import initpoint, dualgrid
+from warnings import warn
+
+class SquareNet:
+    """
+    An iterative grid-straightening algorithm that untangles a D-dimensional mesh 
+    by sorting nodes along each spatial axis to enforce a structured ordering.
+    
+    The grid is represented as an (I, J, ..., D) array, where D is the number of spatial dimensions.
+    Each iteration attempts to minimize disorder along each dimension independently.
+    """
+    
+    def __init__(self, IJ_=(100, 100), max_iter=100, warnings_=True):
+        """
+        Initialize the SquareNet.
+
+        Args:
+            IJ_ (tuple): Grid dimensions (Rows, Cols, ...). Supports any number of dimensions.
+            max_iter (int): Maximum number of straightening iterations.
+            warnings_ (bool): Flag to shut up all warnings if asked
+        """
+        self.IJ_ = tuple(IJ_)
+        self.D = len(IJ_)  # Spatial dimensions (x, y, z,...)
+        self.N = np.prod(IJ_)
+        self.max_iter = max_iter
+        self.learning_curve = []
+        self.warnings_ = warnings_
+        
+        # Internal state
+        self.points = None   # Points as given by the user
+        self.heuristics = None # Heuristics is computed on points
+        self.grid =  np.arange(
+            self.N, dtype = np.int32
+        ).reshape(IJ_) #grid to sort heuritics
+        self.invert_grid = dualgrid(self.grid) #for invertibility
+        self.packed = False #Flag for faster computations if possible
+
+    def fit(self, points):
+        """
+        Fit the grid to a set of points in D dimensions.
+
+        Args:
+            points (np.ndarray or str): Array of shape (N, D) or a method name supported
+                                        by .utils.initpoint.
+        """
+        if isinstance(points, str):
+            points = initpoint(method=points, size=(self.N, self.D))
+        
+        N, D = points.shape
+        assert N == self.N, f"Input points ({N}) must match grid size {self.N}"
+        assert D == self.D, f"Input points dimension ({D}) must match D={self.D}"
+
+        self.points = points
+        self.heuristics = carthesian_heuristics(points)
+
+        grid, learning_curve = sort_increasing(
+            self.grid, self.heuristics, self.max_iter
+        )
+
+        last_iter = len(learning_curve) -1
+        last_error = learning_curve[-1]
+
+        if last_iter == 0:
+            #just tacking advantage of situation 
+            #to boost map and invertmap function
+            self.autopack() 
+        
+        elif last_error == 0:
+             print(f"succesfully sorted at iteration {last_iter}")
+
+        else:
+            if self.warnings_:
+                warn(
+                    "Disorder didn't converge to 0. "
+                    "Check the learning curve and consider increasing the max_iter parameter.",
+                    ConvergenceWarning,
+                    stacklevel=2
+                )
+        
+        # Save results
+        self.grid = grid
+        self.invert_grid = dualgrid(grid)
+        self.learning_curve = learning_curve
+    
+    def map(self, features):
+        """
+        Gather: cloud data (N, *C) -> grid data (N1, ..., ND, *C)
+        """
+        if not self.packed:
+            return features[self.grid]
+        C = features.shape[1:]
+        return features.reshape(*self.IJ_, *C)
+    
+    def invert_map(self, features):
+        """
+        Restores: grid data (N1, ..., ND, *C) -> cloud data (N, *C)
+        """
+        if not self.packed:
+            return features.reshape(
+                -1, *features.shape[self.D:]
+                )[self.invert_grid.flatten()]
+        
+        C = features.shape[self.D:]
+        return features.reshape(-1, *C)
+    
+    def mapidx(self, index):
+        """
+        Convert: ONE cloud index -> ONE grid index
+        """
+        return self.invert_grid[index]
+    
+    def invert_mapidx(self, index):
+        """
+        Convert: ONE grid index-> ONE cloud index
+        """
+        return self.grid[tuple(index)]
+               
+    def checkerboard(self, scale = [2, 4, 8, 16], toplot = True, **kwargs):
+        """
+        alias for boards.checkerboard:
+
+        return the net as a checkerboard at required scale = number of cells per axe
+        make a nice plot if self.D = 2 or 3
+
+        **kwargs are extra visualization arguments (color, point size...)
+        """
+        gpoints = np.ascontiguousarray(self.map(self.points))
+        #nice plot if possible
+        if toplot and (self.D == 2):
+            checkerboard2D(gpoints, scale = scale, **kwargs)
+        elif toplot and (self.D == 3):
+            checkerboard3D(gpoints, scale = 8, **kwargs) 
+        else:
+            return checkerboard(gpoints, scale)
+    
+    def views(self, X, wr, map=True, invert_map=False, select_lazy=None, **kwargs):
+        """
+        Alias for views.localview
+
+        Compute local neighborhood views of the input array `X`
+        using rectangular windows of radius `wr`. The window size
+        is given by ``ws = 2 * wr + 1`` (per dimension).
+
+        Parameters
+        ----------
+        X : np.ndarray
+            Input data of shape (N, *C) or (*G, *C).
+        wr : int or tuple (per dimension)
+            Radius of the window.
+        map : bool, default True
+            If True, `X` is assumed to be in (N, *C) space.
+            Otherwise, it is assumed to be in (*G, *C) space.
+        invert_map : bool, default False
+            If True, the output will stay in (*G, *C)  space 
+            Otherwise, it will be converted back to (N, *C) 
+        select_lazy : None or IndexLike, default None
+            Subset of indices where the view is computed.
+            Must be grid indexes
+        **kwargs :
+            Additional keyword arguments passed to `np.pad`
+            (e.g., boundary conditions). See NumPy documentation.
+
+        Returns
+        -------
+        Xview : np.ndarray or WindowCollector
+            - If dense output:
+                Array of shape (N, *C, *ws) or (*G, *C, *ws).
+            - If `select_lazy` is used:
+                A mapping (e.g. dict-like) from selected indices
+                to local views of shape (*G[sel], *C, *ws).
+        """
+        lazy = (select_lazy is not None)
+
+        Xmap = self.map(X) if map else X
+        Xmap = np.ascontiguousarray(Xmap)
+
+        args = (Xmap, wr, self.D)
+
+        Xview = (
+            localview(*args, **kwargs)
+            if not lazy
+            else lazylocalview(select_lazy, *args, **kwargs)
+        )
+
+        if invert_map:
+            if lazy:
+                Xview = {
+                    self.invert_mapidx(key): value
+                    for key, value in Xview.items()
+                }
+            else:
+                if self.warnings_:
+                    warn(
+                        "Using invert_map may be slow and memory-intensive. "
+                        "Consider working with gridded data or enabling select_lazy "
+                        "if you only need a subset of the views.",
+                        PerformanceWarning,
+                        stacklevel=2
+                    )
+                Xview = self.invert_map(Xview)
+         
+        
+        return Xview
+    
+    def autopack(self):
+        print(
+            "Successfully sorted at iteration 0...\n"
+            "...Which means data are allready packed\n"
+            "Performing an autopack to boost performance."
+        )
+        self.packed = True
+
+        if self.warnings_:
+            if not self.points.flags.c_contiguous:
+                warn(
+                    "Consider calling np.ascontiguousarray on your input arrays "
+                    "(e.g., points and covariates) to improve performance.",
+                    PerformanceWarning,
+                    stacklevel=2
+                )
+
+class ConvergenceWarning(UserWarning):
+    pass
+
+class PerformanceWarning(UserWarning):
+    pass