Space Curves (spacecurves, Uzay Eğrileri)

PyPI
Conda
DOI
License: AGPL

Space Curves (spacecurves, Uzay Eğrileri)

# Space Curves (spacecurves) / Uzay Eğrileri

[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://www.python.org/)
[![Version](https://img.shields.io/badge/version-0.1.0-green.svg)]()

> **English** | [Türkçe](#türkçe)

---

## English

### 📌 Overview

**Space Curves (spacecurves)** is a comprehensive Python module for space-filling curves, providing a complete implementation of Hilbert curves and other space-filling curves with advanced features.

### ✨ Features

- **Multi-dimensional support**: 1-5 dimensions
- **Configurable depth**: 1-10 iterations (2^p grid size)
- **3 curve types**: Hilbert, Morton, Moore
- **High performance**: LRU cache support, batch operations
- **Neighbor search**: Find neighbors in Hilbert space
- **Image compression**: Hilbert curve-based image compression
- **Dimension reduction**: High-dimensional data → 2D visualization
- **Hilbert ordering**: Spatial data organization
- **Grid system**: Hilbert-based data structure
- **Path optimization**: TSP-like route optimization
- Görselleştirme araçları (HilbertVisualizer)
- Yaklaşık kümeleme (HilbertClustering)

### 🚀 Quick Start

```python
from spacecurves import SpaceFillingCurve, CurveType

# Create a 2D Hilbert curve (16x16 grid)
curve = SpaceFillingCurve(p=4, n=2)

# Transform: distance → coordinates
point = curve[42]           # [7, 0]

# Inverse transform: coordinates → distance
distance = curve.inverse([7, 0])  # 42

# Batch transform
distances = [0, 10, 20, 30, 40]
points = curve.batch_transform(distances)

# Find neighbors
neighbors = curve.get_neighbors([5, 5], radius=2)

📦 Installation

pip install spacecurves

Or directly from source:

git clone https://github.com/yourusername/spacecurves.git
cd spacecurves
pip install -e .

📚 Examples

1. GPS Coordinate Indexing

from spacecurves import SpaceFillingCurve

curve = SpaceFillingCurve(p=8, n=2)

# City coordinates (latitude, longitude)
cities = {
    'Istanbul': [41.0082, 28.9784],
    'Ankara': [39.9334, 32.8597],
}

# Convert to Hilbert index
for name, coord in cities.items():
    x = int((coord[0] - 36) / 6 * 255)
    y = int((coord[1] - 26) / 15 * 255)
    idx = curve.inverse([x, y])
    print(f"{name}: {idx}")

2. Image Compression

import numpy as np
from spacecurves import HilbertImageCompressor

# Create test image
image = np.random.randint(0, 256, (256, 256), dtype=np.uint8)

# Compress
compressor = HilbertImageCompressor(image)
compressed = compressor.compress(keep_ratio=0.2)  # Keep 20% of pixels

3. Dimension Reduction

from spacecurves import HilbertDimensionReducer

# 10D data → 2D visualization
reducer = HilbertDimensionReducer(target_dim=2, p=6)
reduced = reducer.fit_transform(high_dim_data)

4. Route Optimization

from spacecurves import HilbertPathOptimizer

curve = SpaceFillingCurve(p=8, n=2)
optimizer = HilbertPathOptimizer(curve)

# Optimize delivery route
optimized_route = optimizer.optimize_order(delivery_points)

5. Hilbert Grid

from spacecurves import HilbertGrid

grid = HilbertGrid(curve)
grid[[10, 20]] = "Value A"
grid[[30, 40]] = "Value B"

print(grid[[10, 20]])  # Value A

🔧 API Reference

SpaceFillingCurve(p, n, curve_type=CurveType.HILBERT, use_cache=True)

Methods:

Curve Types

📊 Performance

• Transform speed: ~2.6M ops/sec (2D, p=4)
• Cache hit rate: >95% with repeated queries
• Grid access: ~0.01ms per operation

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later).

👤 Author

Mehmet Keçeci
Email: mkececi@yaani.com

Türkçe

📌 Genel Bakış

Space Curves (spacecurves), uzay dolduran eğriler için kapsamlı bir Python modülüdür. Hilbert eğrisi ve diğer uzay dolduran eğrilerin tam bir implementasyonunu gelişmiş özelliklerle sunar.

✨ Özellikler

• Çok boyutlu destek: 1-5 boyut
• Ayarlanabilir derinlik: 1-16 iterasyon (2^p grid boyutu)
• 3 eğri tipi: Hilbert, Morton, Moore
• Yüksek performans: LRU önbellek, toplu işlemler
• Komşuluk arama: Hilbert uzayında komşu bulma
• Görüntü sıkıştırma: Hilbert eğrisi tabanlı görüntü sıkıştırma
• Boyut indirgeme: Yüksek boyutlu veri → 2D görselleştirme
• Hilbert sıralama: Mekansal veri düzenleme
• Grid sistemi: Hilbert tabanlı veri yapısı
• Rota optimizasyonu: TSP benzeri rota optimizasyonu
• Görselleştirme araçları (HilbertVisualizer)
• Yaklaşık kümeleme (HilbertClustering)

🚀 Hızlı Başlangıç

from spacecurves import SpaceFillingCurve, CurveType

# 2D Hilbert eğrisi oluştur (16x16 grid)
curve = SpaceFillingCurve(p=4, n=2)

# Dönüşüm: mesafe → koordinat
point = curve[42]           # [7, 0]

# Ters dönüşüm: koordinat → mesafe
distance = curve.inverse([7, 0])  # 42

# Toplu dönüşüm
distances = [0, 10, 20, 30, 40]
points = curve.batch_transform(distances)

# Komşu bulma
neighbors = curve.get_neighbors([5, 5], radius=2)

📦 Kurulum

pip install spacecurves

Veya doğrudan kaynaktan:

git clone https://github.com/WhiteSymmetry/spacecurves.git
cd spacecurves
pip install -e .

📚 Örnekler

1. GPS Koordinat İndeksleme

from spacecurves import SpaceFillingCurve

curve = SpaceFillingCurve(p=8, n=2)

# Şehir koordinatları (enlem, boylam)
sehirler = {
    'İstanbul': [41.0082, 28.9784],
    'Ankara': [39.9334, 32.8597],
}

# Hilbert indeksine dönüştür
for ad, koord in sehirler.items():
    x = int((koord[0] - 36) / 6 * 255)
    y = int((koord[1] - 26) / 15 * 255)
    idx = curve.inverse([x, y])
    print(f"{ad}: {idx}")

2. Görüntü Sıkıştırma

import numpy as np
from spacecurves import HilbertImageCompressor

# Test görüntüsü oluştur
gorsel = np.random.randint(0, 256, (256, 256), dtype=np.uint8)

# Sıkıştır
sikistirici = HilbertImageCompressor(gorsel)
sikistirilmis = sikistirici.compress(keep_ratio=0.2)  # Piksellerin %20'sini tut

3. Boyut İndirgeme

from spacecurves import HilbertDimensionReducer

# 10D veri → 2D görselleştirme
indirgeyici = HilbertDimensionReducer(target_dim=2, p=6)
indirgenmis = indirgeyici.fit_transform(yuksek_boyutlu_veri)

4. Rota Optimizasyonu

from spacecurves import HilbertPathOptimizer

curve = SpaceFillingCurve(p=8, n=2)
optimizer = HilbertPathOptimizer(curve)

# Teslimat rotasını optimize et
optimize_rota = optimizer.optimize_order(teslimat_noktalari)

5. Hilbert Grid

from spacecurves import HilbertGrid

grid = HilbertGrid(curve)
grid[[10, 20]] = "Değer A"
grid[[30, 40]] = "Değer B"

print(grid[[10, 20]])  # Değer A

🔧 API Referansı

SpaceFillingCurve(p, n, curve_type=CurveType.HILBERT, use_cache=True)

Metotlar:

Eğri Tipleri

📊 Performans

• Dönüşüm hızı: ~2.6M işlem/saniye (2D, p=4)
• Önbellek isabet oranı: Tekrarlı sorgularda >%95
• Grid erişimi: ~0.01ms işlem başına

📄 Lisans

Bu proje GNU Affero General Public License v3.0 (AGPL-3.0-or-later) ile lisanslanmıştır.

👤 Yazar

Mehmet Keçeci

Acknowledgments / Teşekkürler

• Hilbert curve algorithm based on the work of David Hilbert (1891)
• Morton order (Z-order curve) by Guy Macdonald Morton (1966)
• Moore curve by E. H. Moore (1900)

---

# Pixi:

[![Pixi](https://img.shields.io/badge/Pixi-Pixi-brightgreen.svg)](https://prefix.dev/channels/bilgi)

pixi init spacecurves

cd spacecurves

pixi workspace channel add [https://prefix.dev/channels/bilgi](https://prefix.dev/channels/bilgi) --prepend

✔ Added https://prefix.dev/channels/bilgi

pixi add spacecurves

✔ Added spacecurves >=...,<1

pixi install

pixi shell

pixi run python -c "import spacecurves; print(spacecurves.__version__)"

### Çıktı: 

pixi remove spacecurves

conda install -c https://prefix.dev/channels/bilgi spacecurves

pixi run python -c "import spacecurves; print(spacecurves.__version__)"

### Çıktı: 

pixi run pip list | grep spacecurves

### spacecurves  

pixi run pip show spacecurves

Name: spacecurves

Version: 

Summary: Keçeci Numbers: Keçeci Sayıları (Keçeci Conjecture)

Home-page: https://github.com/WhiteSymmetry/spacecurves

Author: Mehmet Keçeci

Author-email: Mehmet Keçeci <...>

License: GNU AFFERO GENERAL PUBLIC LICENSE

Copyright (c) 2025-2026 Mehmet Keçeci

----

1. https://pypi.org/project/spacecurves/
2. https://anaconda.org/bilgi/spacecurves
3. https://prefix.dev/channels/bilgi/packages/spacecurves

---

## License / Lisans

This project is licensed under the AGPL3.0 or Later License. See the `LICENSE` file for details.

## Citation

If this library was useful to you in your research, please cite us. Following the [GitHub citation standards](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files), here is the recommended citation.

### BibTeX

```bibtex
@misc{kececi_2026_19672791,
  author       = {Keçeci, Mehmet},
  title        = {spacecurves},
  month        = apr,
  year         = 2026,
  publisher    = {Zenodo},
  version      = {0.1.3},
  doi          = {10.5281/zenodo.19672791},
  url          = {https://doi.org/10.5281/zenodo.19672791},
}

APA

Keçeci, M. (2026). spacecurves (0.1.3). Open Science Articles (OSAs), Zenodo. https://doi.org/10.5281/zenodo.19672791