# GRIDR Release Notes v0.5.0

**Release Date:** 2026-01-13  
**Type:** Major Feature Release

---

## 🎯 What's New

### B-Spline Interpolation

B-Spline interpolation is now available in GRIDR, delivering smoother results than traditional linear interpolation.

**Available orders:** 3, 5, 7, 9, and 11.

```python
from gridr.core.interp.interpolator import BSpline5Interpolator

# Create a B-Spline interpolator of order 5
interpolator = BSpline5Interpolator(epsilon=1e-4, mask_influence_threshold=0.001)
```

**Important:** B-Spline interpolation automatically handles masked/invalid pixels, preventing artifacts from propagating into your results.

---

### Standalone Mode - Simplified Workflow for the Core method

New **standalone mode** makes grid resampling easier than ever! Just enable it and GRIDR automatically handles all the complex preprocessing steps:

```python
from gridr.core.grid.grid_resampling import array_grid_resampling

result = array_grid_resampling(
    src_array=image,
    grid_x=target_x,
    grid_y=target_y,
    interpolator="cubic",
    standalone=True  # ← Enable standalone mode
)
```

What standalone mode does for you:
- ✅ Computes grid metrics automatically
- ✅ Detects required source regions
- ✅ Applies padding when needed
- ✅ Performs B-Spline prefiltering
- ✅ Handles masked data correctly

**No more manual data preprocessing!** Perfect for quick prototyping.

---

### Boundary Conditions

Control how pixels are handled at image borders with four new boundary modes:

| Mode | Description |
|------|-------------|
| `'edge'` | Repeat edge pixels |
| `'reflect'` | Mirror at boundaries |
| `'symmetric'` | Symmetric reflection |
| `'wrap'` | Wrap to opposite edge |

**Available** for both **Core** and **Chain** Grid Resampling methods!

```python
result = array_grid_resampling(
    ...,
    boundary_condition='reflect',  # Choose your mode
    standalone=True
)
```

**Eliminates edge artifacts** - No more black borders or strange values at image edges!

---

### Grid Coordinates Shifting

The introduction of the `grid_shift` parameter now enables seamless adaptation to various grid pixel coordinate system conventions, providing greater flexibility and compatibility across different imaging tools.

```python
from gridr.chain.grid_resampling_chain import basic_grid_resampling_chain

chain = basic_grid_resampling_chain(
    ...,
    grid_shift=(0.5, 0.5)  # Shift by half a pixel
)
```

---

## 🛡️ Improved Stability & Safety

### Automatic Safety Checks

GRIDR now automatically detects and prevents out-of-bounds errors when working with complex geometric transformations:

- **Safe handling** of non-topology-preserving grids
- **Automatic detection** of valid source regions

### Enhanced Numerical Precision

Floating-point precision issues have been resolved, addressing potential problems with:
- ❌ Nearest-neighbor interpolation selecting wrong pixels
- ❌ Inconsistent results between the Core and the Chain resampling methods for Nearest-neighbor interpolation.

---

## 📚 Breaking Changes

### ⚠️ Interpolator Creation

**What changed:** Interpolators must now be created as Python objects before passing to the Rust core resampling functions.

**Before (v0.4.x):**
```python
array_grid_resampling(..., interpolator='cubic')
```

**Now (v0.5.0):**
```python
from gridr.core.interp.interpolator import OptimizedCubicInterpolator, get_interpolator

# Still working for python functions
interp = BilinearInterpolator()
array_grid_resampling(..., interpolator="cubic")

# New interpolator object
interp = OptimizedBicubicInterpolator()
array_grid_resampling(..., interpolator=interp)

# New helper method
interp = get_interpolator("cubic")
array_grid_resampling(..., interpolator=interp)

```

**Why?** This enables advanced features like parametrized/stateful interpolators and shared pretabulated coefficients.

---

## 📖 Documentation Updates

### New Resources

- **Theoretical Foundations** - Mathematical details of grid resampling conventions
- **Updated Users Guide** - Addition of a section to the user guide for new features

### Improved Math Rendering

Documentation now uses MathJax 3 for faster, more reliable equation rendering, and includes citation support for academic references.

---

## 🔧 Migration Guide

### Updating Your Code

**Step 1:** Consider using standalone mode

```python
# Simplify your code with standalone mode
result = array_grid_resampling(
    src_array=image,
    grid_x=grid_x,
    grid_y=grid_y,
    interpolator=interp,
    standalone=True  # Add this!
)
```

**Step 2:** Add boundary conditions if needed

```python
result = array_grid_resampling(
    ...,
    boundary_condition='reflect',  # Prevent edge artifacts
    standalone=True
)
```

---

## 🐛 Bug Fixes

- Fixed crashes when resampling with extreme geometric transformations
- Fixed nearest-neighbor interpolation precision errors
- Added missing Shapely dependency
- Improved notebook CSS styling for better readability

---

## 📦 Installation

```bash
pip install --upgrade gridr
```

**Requirements:**
- Python ≥ 3.10
- PyO3 ≥ 0.27.2

---

## 💬 Need Help?

- 📖 **Documentation:** [https://gridr.readthedocs.io/](https://gridr.readthedocs.io/)
- 🐛 **Report Issues:** [GitHub Issues](https://github.com/CNES/gridr/issues)
- 💡 **Discussions:** [GitHub Discussions](https://github.com/CNES/gridr/discussions)