Metadata-Version: 2.4
Name: squarenet
Version: 0.1.0
Summary: Sparse local operations for point clouds in any dimension.
Author-email: ArmanddeCacqueray <armanddecacqueray@sfr.fr>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: matplotlib
Provides-Extra: demo
Requires-Dist: geopandas; extra == "demo"
Requires-Dist: shapely; extra == "demo"
Dynamic: license-file

# SquareNet

**SquareNet** is a lightweight framework for mapping unstructured point clouds into structured N-dimensional grids, enabling fast and efficient local operations.

## ✨ Key Idea

SquareNet builds a bijective mapping between point indices and a structured grid:

* **Bijection**: each point maps to exactly one grid cell
* **Neighborhood preservation**: nearby points remain close in the grid

This allows replacing expensive spatial queries (k-NN, radius search) with simple **array slicing**.

---

## 🚀 Features

* Fast point cloud → grid mapping
* Invertible transformation
* Efficient local neighborhood operations
* Sparse Gram matrix computation via sliding windows
* NumPy-friendly (no heavy dependencies required)

---

## 📦 Installation

```bash
pip install squarenet
```

---

## 🧠 Basic Usage

```python
from squarenet import SquareNet

sqnet = SquareNet(IJ=(L, W, H, ...), max_iter = 100)

# Original data: (N, D)
points = np.random.rand(N, D)
Sqnet.fit(points)

# Map (N, *) to the grid: (L, W, H, ..., *)
sqX = sqnet.map(X)

# Back to original ordering
X_rec = sqnet.invert_map(sqX)
```

---

## 🔬 Local Processing Example

Compute a **local (sparse) Gram matrix** using a sliding window:

```python
G = sqnet.gram(X, ws=(5, 5))
```

Instead of computing a full `(N × N)` matrix, SquareNet only computes interactions within local neighborhoods.

---

## 🗺️ Demo Dataset

A small demo dataset (France map) is included:

```python
Sqnet.fit("france")
```

---

## 🧱 Project Structure

```
src/
  squarenet/
    __init__.py
    core.py
    utils.py
    data/france.geojson
```

---

## 🎯 Why SquareNet?

Traditional point cloud pipelines rely on:

* k-NN search (O(N log N))
* irregular memory access
* poor GPU utilization

SquareNet enables:

* **O(N)** local operations
* contiguous memory access
* vectorized operations on a sliding window

---

## 📈 Use Cases

* Point cloud processing
* Graph-to-grid transformations
* Fast kernel methods
* Local feature aggregation
* Deep learning preprocessing

---

## 🛠️ Development

```bash
git clone https://github.com/ArmanddeCacqueray/SquareNet
cd squarenet
pip install -e .
```

---

## 📄 License

MIT License

---

## 🤝 Contributing

Contributions are welcome. Please open an issue or submit a pull request.

