| Name | torch-cubic-spline-grids JSON |
| Version |
0.0.8
JSON |
| download |
| home_page | |
| Summary | Cubic spline interpolation on multidimensional grids in PyTorch |
| upload_time | 2023-03-27 11:57:15 |
| maintainer | |
| docs_url | None |
| author | Alister Burt |
| requires_python | >=3.8 |
| license | BSD 3-Clause License |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# torch-cubic-spline-grids
[](https://github.com/alisterburt/torch-cubic-spline-grids/raw/main/LICENSE)
[](https://pypi.org/project/torch-cubic-spline-grids)
[](https://python.org)
[](https://github.com/alisterburt/torch-cubic-spline-grids/actions/workflows/ci.yml)
[](https://codecov.io/gh/alisterburt/torch-cubic-spline-grids)
*Cubic spline interpolation on multidimensional grids in PyTorch.*
The primary goal of this package is to provide learnable, continuous
parametrisations of 1-4D spaces.
---
## Overview
`torch_cubic_spline_grids` provides a set of PyTorch components called grids.
Grids are defined by
- their dimensionality (1d, 2d, 3d, 4d...)
- the number of points covering each dimension (`resolution`)
- the number of values stored on each grid point (`n_channels`)
- how we interpolate between values on grid points
All grids in this package consist of uniformly spaced points covering the full
extend of each dimension.
### First steps
Let's make a simple 2D grid with one value on each grid point.
```python
import torch
from torch_cubic_spline_grids import CubicBSplineGrid2d
grid = CubicBSplineGrid2d(resolution=(5, 3), n_channels=1)
```
- `grid.ndim` is `2`
- `grid.resolution` is `(5, 3)` (or `(h, w)`)
- `grid.n_channels` is `1`
- `grid.data.shape` is `(1, 5, 3)` (or `(c, h, w)`)
In words, the grid extends over two dimensions `(h, w)` with 5 points
in `h` and `3` points in `w`.
There is one value stored at each point on the 2D grid.
The grid data is stored in a tensor of shape `(c, *grid_resolution)`.
We can obtain the value (interpolant) at any continuous point on the grid.
The grid coordinate system extends from `[0, 1]` along each grid dimension.
The interpolant is obtained by sequential application of
cubic spline interpolation along each dimension of the grid.
```python
coords = torch.rand(size=(10, 2)) # values in [0, 1]
interpolants = grid(coords)
```
- `interpolants.shape` is `(10, 1)`
### Optimisation
Values at each grid point can be optimised by minimising a loss function associated with grid interpolants.
In this way the continuous space of the grid can be made to more accurately model a 1-4D space.
<p align="center" width="100%">
<img width="60%" src="https://user-images.githubusercontent.com/7307488/226992179-049a63a0-a2f3-4432-b38e-6e8bcaa6a4a8.png">
</p>
The image above shows the values of 6 control points on a 1D grid being optimised such
that interpolating between them with cubic B-spline interpolation approximates a single oscillation of a sine wave.
Notebooks are available for this
[1D example](./examples/optimise_1d_grid.ipynb)
and a similar
[2D example](./examples/optimise_2d_grid.ipynb).
### Types of grids
`torch_cubic_spline_grids` provides grids which can be interpolated with **cubic
B-spline** interpolation or **cubic Catmull-Rom spline** interpolation.
| spline | continuity | interpolating? |
|--------------------|------------|----------------|
| cubic B-spline | C2 | No |
| Catmull-Rom spline | C1 | Yes |
If your need the resulting curve to intersect the data on the grid you should
use the cubic Catmull-Rom spline grids
- `CubicCatmullRomGrid1d`
- `CubicCatmullRomGrid2d`
- `CubicCatmullRomGrid3d`
- `CubicCatmullRomGrid4d`
If you require continuous second derivatives then the cubic B-spline grids are more
suitable.
- `CubicBSplineGrid1d`
- `CubicBSplineGrid2d`
- `CubicBSplineGrid3d`
- `CubicBSplineGrid4d`
### Regularisation
The number of points in each dimension should be chosen such that interpolating on the
grid can approximate the underlying phenomenon being modelled without overfitting.
A low resolution grid provides a regularising effect by smoothing the model.
## Installation
`torch_cubic_spline_grids` is available on PyPI
```shell
pip install torch-cubic-spline-grids
```
## Related work
This is a PyTorch implementation of the way
[Warp](http://warpem.com/warp/#) models continuous deformation
fields and locally variable optical parameters in cryo-EM images.
The approach is described in
[Dimitry Tegunov's paper](https://doi.org/10.1038/s41592-019-0580-y):
> Many methods in Warp are based on a continuous parametrization of 1- to
> 3-dimensional spaces.
> This parameterization is achieved by spline interpolation between points on a coarse,
> uniform grid, which is computationally efficient.
> A grid extends over the entirety of each dimension that needs to be modeled.
> The grid resolution is defined by the number of control points in each dimension
> and is scaled according to physical constraints
> (for example, the number of frames or pixels) and available signal.
> The latter provides regularization to prevent overfitting of sparse data with too many
> parameters.
> When a parameter described by the grid is retrieved for a point in space (and time),
> for example for a particle (frame), B-spline interpolation is performed at that point
> on the grid.
> To fit a grid’s parameters, in general, a cost function associated with the
> interpolants at specific positions on the grid is optimized.
---
For a fantastic introduction to splines I recommend
[Freya Holmer](https://www.youtube.com/watch?v=jvPPXbo87ds)'s YouTube video.
[The Continuity of Splines - YouTube](https://youtu.be/jvPPXbo87ds)
Raw data
{
"_id": null,
"home_page": "",
"name": "torch-cubic-spline-grids",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Alister Burt",
"author_email": "alisterburt@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b9/e7/24dd5f302a0f80c7fd66d3744f5e3e90d06fe2dd98450efcb6cbb9a25a54/torch_cubic_spline_grids-0.0.8.tar.gz",
"platform": null,
"description": "# torch-cubic-spline-grids\n\n[](https://github.com/alisterburt/torch-cubic-spline-grids/raw/main/LICENSE)\n[](https://pypi.org/project/torch-cubic-spline-grids)\n[](https://python.org)\n[](https://github.com/alisterburt/torch-cubic-spline-grids/actions/workflows/ci.yml)\n[](https://codecov.io/gh/alisterburt/torch-cubic-spline-grids)\n\n*Cubic spline interpolation on multidimensional grids in PyTorch.*\n\nThe primary goal of this package is to provide learnable, continuous\nparametrisations of 1-4D spaces.\n\n--- \n\n## Overview\n\n`torch_cubic_spline_grids` provides a set of PyTorch components called grids.\n\nGrids are defined by\n- their dimensionality (1d, 2d, 3d, 4d...)\n- the number of points covering each dimension (`resolution`)\n- the number of values stored on each grid point (`n_channels`)\n- how we interpolate between values on grid points\n\nAll grids in this package consist of uniformly spaced points covering the full \nextend of each dimension.\n\n### First steps\nLet's make a simple 2D grid with one value on each grid point.\n\n```python\nimport torch\nfrom torch_cubic_spline_grids import CubicBSplineGrid2d\n\ngrid = CubicBSplineGrid2d(resolution=(5, 3), n_channels=1)\n```\n\n- `grid.ndim` is `2`\n- `grid.resolution` is `(5, 3)` (or `(h, w)`) \n- `grid.n_channels` is `1`\n- `grid.data.shape` is `(1, 5, 3)` (or `(c, h, w)`)\n\nIn words, the grid extends over two dimensions `(h, w)` with 5 points \nin `h` and `3` points in `w`. \nThere is one value stored at each point on the 2D grid. \nThe grid data is stored in a tensor of shape `(c, *grid_resolution)`.\n\nWe can obtain the value (interpolant) at any continuous point on the grid.\nThe grid coordinate system extends from `[0, 1]` along each grid dimension. \nThe interpolant is obtained by sequential application of\ncubic spline interpolation along each dimension of the grid.\n\n```python\ncoords = torch.rand(size=(10, 2)) # values in [0, 1]\ninterpolants = grid(coords)\n```\n\n- `interpolants.shape` is `(10, 1)`\n\n### Optimisation\n\nValues at each grid point can be optimised by minimising a loss function associated with grid interpolants. \nIn this way the continuous space of the grid can be made to more accurately model a 1-4D space.\n\n<p align=\"center\" width=\"100%\">\n <img width=\"60%\" src=\"https://user-images.githubusercontent.com/7307488/226992179-049a63a0-a2f3-4432-b38e-6e8bcaa6a4a8.png\">\n</p>\n\nThe image above shows the values of 6 control points on a 1D grid being optimised such \nthat interpolating between them with cubic B-spline interpolation approximates a single oscillation of a sine wave. \n\nNotebooks are available for this \n[1D example](./examples/optimise_1d_grid.ipynb) \nand a similar \n[2D example](./examples/optimise_2d_grid.ipynb).\n\n### Types of grids\n\n`torch_cubic_spline_grids` provides grids which can be interpolated with **cubic \nB-spline** interpolation or **cubic Catmull-Rom spline** interpolation. \n\n| spline | continuity | interpolating? |\n|--------------------|------------|----------------|\n| cubic B-spline | C2 | No |\n| Catmull-Rom spline | C1 | Yes |\n\nIf your need the resulting curve to intersect the data on the grid you should\nuse the cubic Catmull-Rom spline grids \n\n- `CubicCatmullRomGrid1d`\n- `CubicCatmullRomGrid2d`\n- `CubicCatmullRomGrid3d`\n- `CubicCatmullRomGrid4d`\n\nIf you require continuous second derivatives then the cubic B-spline grids are more \nsuitable.\n\n- `CubicBSplineGrid1d`\n- `CubicBSplineGrid2d`\n- `CubicBSplineGrid3d`\n- `CubicBSplineGrid4d`\n\n### Regularisation\n\nThe number of points in each dimension should be chosen such that interpolating on the \ngrid can approximate the underlying phenomenon being modelled without overfitting. \nA low resolution grid provides a regularising effect by smoothing the model.\n\n\n## Installation\n\n`torch_cubic_spline_grids` is available on PyPI\n\n```shell\npip install torch-cubic-spline-grids\n```\n\n\n## Related work\n\nThis is a PyTorch implementation of the way\n[Warp](http://warpem.com/warp/#) models continuous deformation\nfields and locally variable optical parameters in cryo-EM images. \nThe approach is described in\n[Dimitry Tegunov's paper](https://doi.org/10.1038/s41592-019-0580-y):\n\n> Many methods in Warp are based on a continuous parametrization of 1- to\n> 3-dimensional spaces.\n> This parameterization is achieved by spline interpolation between points on a coarse,\n> uniform grid, which is computationally efficient.\n> A grid extends over the entirety of each dimension that needs to be modeled.\n> The grid resolution is defined by the number of control points in each dimension\n> and is scaled according to physical constraints\n> (for example, the number of frames or pixels) and available signal.\n> The latter provides regularization to prevent overfitting of sparse data with too many\n> parameters.\n> When a parameter described by the grid is retrieved for a point in space (and time),\n> for example for a particle (frame), B-spline interpolation is performed at that point\n> on the grid.\n> To fit a grid\u2019s parameters, in general, a cost function associated with the\n> interpolants at specific positions on the grid is optimized. \n\n---\n\nFor a fantastic introduction to splines I recommend \n[Freya Holmer](https://www.youtube.com/watch?v=jvPPXbo87ds)'s YouTube video.\n\n[The Continuity of Splines - YouTube](https://youtu.be/jvPPXbo87ds)\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Cubic spline interpolation on multidimensional grids in PyTorch",
"version": "0.0.8",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ed33dbcd43ae6b682778690ca285733d561f47ba78a2534e34c98372ca2f8a7f",
"md5": "c68209f8908c18d9192e10fe18ceab30",
"sha256": "6d0de7aac91136120dc33e20f7e620fe4c3763b6b74f585e363f026cb1a58dc1"
},
"downloads": -1,
"filename": "torch_cubic_spline_grids-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c68209f8908c18d9192e10fe18ceab30",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14425,
"upload_time": "2023-03-27T11:57:13",
"upload_time_iso_8601": "2023-03-27T11:57:13.979870Z",
"url": "https://files.pythonhosted.org/packages/ed/33/dbcd43ae6b682778690ca285733d561f47ba78a2534e34c98372ca2f8a7f/torch_cubic_spline_grids-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9e724dd5f302a0f80c7fd66d3744f5e3e90d06fe2dd98450efcb6cbb9a25a54",
"md5": "12373a0a752d89452e21fe7aecd53be1",
"sha256": "fd16315635eb7d0e2a97c8982c6f878c20edf875532b3a0f980280065b4a5353"
},
"downloads": -1,
"filename": "torch_cubic_spline_grids-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "12373a0a752d89452e21fe7aecd53be1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 148834,
"upload_time": "2023-03-27T11:57:15",
"upload_time_iso_8601": "2023-03-27T11:57:15.542158Z",
"url": "https://files.pythonhosted.org/packages/b9/e7/24dd5f302a0f80c7fd66d3744f5e3e90d06fe2dd98450efcb6cbb9a25a54/torch_cubic_spline_grids-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-27 11:57:15",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "torch-cubic-spline-grids"
}
