| Name | torch-interpol JSON |
| Version |
0.2.6
JSON |
| download |
| home_page | None |
| Summary | High-order spline interpolation in PyTorch |
| upload_time | 2024-09-13 08:04:39 |
| maintainer | None |
| docs_url | None |
| author | Yael Balbastre |
| requires_python | >=3.6 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# torch-interpol
High-order spline interpolation in PyTorch
## Description
This package contains a pure python implementation of **high-order spline
interpolation** for ND tensors (including 2D and 3D images). It makes use
of the just-in-time capabilities of TorchScript and explicitly implements
the forward and backward passes of all functions, making it **fast** and
**memory-efficient**.
All the functions available in this (small) package were originally
implemented in [NITorch](https://github/balbasty/nitorch), a larger
PyTorch-based package dedicated to NeuroImaging and Medical Image Computing.
## Installation
### Dependency
- `torch >= 1.3`
### Conda
```shell
conda install torch-interpol -c balbasty -c pytorch
```
### Pip
```shell
pip install torch-interpol
```
## Usage
**See our [example notebooks](examples/)**
## Quick doc
```
Notes
-----
`interpolation` can be an int, a string or an InterpolationType.
Possible values are:
- 0 or 'nearest'
- 1 or 'linear'
- 2 or 'quadratic'
- 3 or 'cubic'
- 4 or 'fourth'
- 5 or 'fifth'
- etc.
A list of values can be provided, in the order [W, H, D],
to specify dimension-specific interpolation orders.
`bound` can be an int, a string or a BoundType.
Possible values are:
- 'replicate' or 'nearest' : a a a | a b c d | d d d
- 'dct1' or 'mirror' : d c b | a b c d | c b a
- 'dct2' or 'reflect' : c b a | a b c d | d c b
- 'dst1' or 'antimirror' : -b -a 0 | a b c d | 0 -d -c
- 'dst2' or 'antireflect' : -c -b -a | a b c d | -d -c -b
- 'dft' or 'wrap' : b c d | a b c d | a b c
- 'zero' or 'zeros' : 0 0 0 | a b c d | 0 0 0
A list of values can be provided, in the order [W, H, D],
to specify dimension-specific boundary conditions.
Note that
- `dft` corresponds to circular padding
- `dct2` corresponds to Neumann boundary conditions (symmetric)
- `dst2` corresponds to Dirichlet boundary conditions (antisymmetric)
See https://en.wikipedia.org/wiki/Discrete_cosine_transform
https://en.wikipedia.org/wiki/Discrete_sine_transform
```
```python
interpol.grid_pull(
input,
grid,
interpolation='linear',
bound='zero',
extrapolate=False,
prefilter=False,
)
"""
Sample an image with respect to a deformation field.
If the input dtype is not a floating point type, the input image is
assumed to contain labels. Then, unique labels are extracted
and resampled individually, making them soft labels. Finally,
the label map is reconstructed from the individual soft labels by
assigning the label with maximum soft value.
Parameters
----------
input : (..., [channel], *inshape) tensor
Input image.
grid : (..., *outshape, dim) tensor
Transformation field.
interpolation : int or sequence[int], default=1
Interpolation order.
bound : BoundType or sequence[BoundType], default='zero'
Boundary conditions.
extrapolate : bool or int, default=True
Extrapolate out-of-bound data.
prefilter : bool, default=False
Apply spline pre-filter (= interpolates the input)
Returns
-------
output : (..., [channel], *outshape) tensor
Deformed image.
"""
```
```python
interpol.grid_push(
input,
grid,
shape=None,
interpolation='linear',
bound='zero',
extrapolate=False,
prefilter=False,
)
"""
Splat an image with respect to a deformation field (pull adjoint).
Parameters
----------
input : (..., [channel], *inshape) tensor
Input image.
grid : (..., *inshape, dim) tensor
Transformation field.
shape : sequence[int], default=inshape
Output shape
interpolation : int or sequence[int], default=1
Interpolation order.
bound : BoundType, or sequence[BoundType], default='zero'
Boundary conditions.
extrapolate : bool or int, default=True
Extrapolate out-of-bound data.
prefilter : bool, default=False
Apply spline pre-filter.
Returns
-------
output : (..., [channel], *shape) tensor
Spatted image.
"""
```
```python
interpol.grid_grad(
input,
grid,
interpolation='linear',
bound='zero',
extrapolate=False,
prefilter=False,
)
"""
Sample spatial gradients of an image with respect to a deformation field.
Parameters
----------
input : (..., [channel], *inshape) tensor
Input image.
grid : (..., *inshape, dim) tensor
Transformation field.
shape : sequence[int], default=inshape
Output shape
interpolation : int or sequence[int], default=1
Interpolation order.
bound : BoundType, or sequence[BoundType], default='zero'
Boundary conditions.
extrapolate : bool or int, default=True
Extrapolate out-of-bound data.
prefilter : bool, default=False
Apply spline pre-filter (= interpolates the input)
Returns
-------
output : (..., [channel], *shape, dim) tensor
Sampled gradients.
"""
```
```python
interpol.spline_coeff_nd(
input,
interpolation='linear',
bound='dct2',
dim=None,
inplace=False,
)
"""
Compute the interpolating spline coefficients, for a given spline order
and boundary conditions, along the last `dim` dimensions.
References
----------
..[1] M. Unser, A. Aldroubi and M. Eden.
"B-Spline Signal Processing: Part I-Theory,"
IEEE Transactions on Signal Processing 41(2):821-832 (1993).
..[2] M. Unser, A. Aldroubi and M. Eden.
"B-Spline Signal Processing: Part II-Efficient Design and Applications,"
IEEE Transactions on Signal Processing 41(2):834-848 (1993).
..[3] M. Unser.
"Splines: A Perfect Fit for Signal and Image Processing,"
IEEE Signal Processing Magazine 16(6):22-38 (1999).
Parameters
----------
input : (..., *spatial) tensor
Input image.
interpolation : int or sequence[int], default=1
Interpolation order.
bound : BoundType or sequence[BoundType], default='dct1'
Boundary conditions.
dim : int, default=-1
Number of spatial dimensions
inplace : bool, default=False
Process the volume in place.
Returns
-------
output : (..., *spatial) tensor
Coefficient image.
"""
```
```python
interpol.resize(
image,
factor=None,
shape=None,
anchor='c',
interpolation=1,
prefilter=True
)
"""Resize an image by a factor or to a specific shape.
Notes
-----
.. A least one of `factor` and `shape` must be specified
.. If `anchor in ('centers', 'edges')`, exactly one of `factor` or
`shape must be specified.
.. If `anchor in ('first', 'last')`, `factor` must be provided even
if `shape` is specified.
.. Because of rounding, it is in general not assured that
`resize(resize(x, f), 1/f)` returns a tensor with the same shape as x.
edges centers first last
e - + - + - e + - + - + - + + - + - + - + + - + - + - +
| . | . | . | | c | . | c | | f | . | . | | . | . | . |
+ _ + _ + _ + + _ + _ + _ + + _ + _ + _ + + _ + _ + _ +
| . | . | . | | . | . | . | | . | . | . | | . | . | . |
+ _ + _ + _ + + _ + _ + _ + + _ + _ + _ + + _ + _ + _ +
| . | . | . | | c | . | c | | . | . | . | | . | . | l |
e _ + _ + _ e + _ + _ + _ + + _ + _ + _ + + _ + _ + _ +
Parameters
----------
image : (batch, channel, *inshape) tensor
Image to resize
factor : float or list[float], optional
Resizing factor
* > 1 : larger image <-> smaller voxels
* < 1 : smaller image <-> larger voxels
shape : (ndim,) list[int], optional
Output shape
anchor : {'centers', 'edges', 'first', 'last'} or list, default='centers'
* In cases 'c' and 'e', the volume shape is multiplied by the
zoom factor (and eventually truncated), and two anchor points
are used to determine the voxel size.
* In cases 'f' and 'l', a single anchor point is used so that
the voxel size is exactly divided by the zoom factor.
This case with an integer factor corresponds to subslicing
the volume (e.g., `vol[::f, ::f, ::f]`).
* A list of anchors (one per dimension) can also be provided.
interpolation : int or sequence[int], default=1
Interpolation order.
prefilter : bool, default=True
Apply spline pre-filter (= interpolates the input)
Returns
-------
resized : (batch, channel, *shape) tensor
Resized image
"""
```
## License
torch-interpol is released under the MIT license.
Raw data
{
"_id": null,
"home_page": null,
"name": "torch-interpol",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Yael Balbastre",
"author_email": "yael.balbastre@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cb/36/f2bcf9ba3de378532b007390356ca2bdd5649c5ab6d72595bf422d202c73/torch-interpol-0.2.6.tar.gz",
"platform": "OS Independent",
"description": "# torch-interpol\nHigh-order spline interpolation in PyTorch\n\n## Description\n\nThis package contains a pure python implementation of **high-order spline \ninterpolation** for ND tensors (including 2D and 3D images). It makes use \nof the just-in-time capabilities of TorchScript and explicitly implements\nthe forward and backward passes of all functions, making it **fast** and \n**memory-efficient**. \n\nAll the functions available in this (small) package were originally \nimplemented in [NITorch](https://github/balbasty/nitorch), a larger \nPyTorch-based package dedicated to NeuroImaging and Medical Image Computing.\n\n## Installation\n\n### Dependency\n\n- `torch >= 1.3`\n\n### Conda\n\n```shell\nconda install torch-interpol -c balbasty -c pytorch\n```\n\n### Pip\n\n```shell\npip install torch-interpol\n```\n\n## Usage\n\n**See our [example notebooks](examples/)**\n\n## Quick doc\n\n\n```\nNotes\n-----\n\n`interpolation` can be an int, a string or an InterpolationType.\nPossible values are:\n - 0 or 'nearest'\n - 1 or 'linear'\n - 2 or 'quadratic'\n - 3 or 'cubic'\n - 4 or 'fourth'\n - 5 or 'fifth'\n - etc.\nA list of values can be provided, in the order [W, H, D],\nto specify dimension-specific interpolation orders.\n\n`bound` can be an int, a string or a BoundType.\nPossible values are:\n - 'replicate' or 'nearest' : a a a | a b c d | d d d\n - 'dct1' or 'mirror' : d c b | a b c d | c b a\n - 'dct2' or 'reflect' : c b a | a b c d | d c b\n - 'dst1' or 'antimirror' : -b -a 0 | a b c d | 0 -d -c\n - 'dst2' or 'antireflect' : -c -b -a | a b c d | -d -c -b\n - 'dft' or 'wrap' : b c d | a b c d | a b c\n - 'zero' or 'zeros' : 0 0 0 | a b c d | 0 0 0\nA list of values can be provided, in the order [W, H, D],\nto specify dimension-specific boundary conditions.\nNote that\n- `dft` corresponds to circular padding\n- `dct2` corresponds to Neumann boundary conditions (symmetric)\n- `dst2` corresponds to Dirichlet boundary conditions (antisymmetric)\nSee https://en.wikipedia.org/wiki/Discrete_cosine_transform\n https://en.wikipedia.org/wiki/Discrete_sine_transform\n```\n\n```python\ninterpol.grid_pull(\n input,\n grid,\n interpolation='linear',\n bound='zero',\n extrapolate=False,\n prefilter=False,\n)\n\"\"\"\nSample an image with respect to a deformation field.\n\nIf the input dtype is not a floating point type, the input image is \nassumed to contain labels. Then, unique labels are extracted \nand resampled individually, making them soft labels. Finally, \nthe label map is reconstructed from the individual soft labels by \nassigning the label with maximum soft value.\n\nParameters\n----------\ninput : (..., [channel], *inshape) tensor\n Input image.\ngrid : (..., *outshape, dim) tensor\n Transformation field.\ninterpolation : int or sequence[int], default=1\n Interpolation order.\nbound : BoundType or sequence[BoundType], default='zero'\n Boundary conditions.\nextrapolate : bool or int, default=True\n Extrapolate out-of-bound data.\nprefilter : bool, default=False\n Apply spline pre-filter (= interpolates the input)\n\nReturns\n-------\noutput : (..., [channel], *outshape) tensor\n Deformed image.\n\"\"\"\n```\n\n```python\ninterpol.grid_push(\n input,\n grid,\n shape=None,\n interpolation='linear',\n bound='zero',\n extrapolate=False,\n prefilter=False,\n)\n\"\"\"\nSplat an image with respect to a deformation field (pull adjoint).\n\nParameters\n----------\ninput : (..., [channel], *inshape) tensor\n Input image.\ngrid : (..., *inshape, dim) tensor\n Transformation field.\nshape : sequence[int], default=inshape\n Output shape\ninterpolation : int or sequence[int], default=1\n Interpolation order.\nbound : BoundType, or sequence[BoundType], default='zero'\n Boundary conditions.\nextrapolate : bool or int, default=True\n Extrapolate out-of-bound data.\nprefilter : bool, default=False\n Apply spline pre-filter.\n\nReturns\n-------\noutput : (..., [channel], *shape) tensor\n Spatted image.\n\"\"\"\n```\n\n```python\ninterpol.grid_grad(\n input,\n grid,\n interpolation='linear',\n bound='zero',\n extrapolate=False,\n prefilter=False,\n)\n\"\"\"\nSample spatial gradients of an image with respect to a deformation field.\n\nParameters\n----------\ninput : (..., [channel], *inshape) tensor\n Input image.\ngrid : (..., *inshape, dim) tensor\n Transformation field.\nshape : sequence[int], default=inshape\n Output shape\ninterpolation : int or sequence[int], default=1\n Interpolation order.\nbound : BoundType, or sequence[BoundType], default='zero'\n Boundary conditions.\nextrapolate : bool or int, default=True\n Extrapolate out-of-bound data.\nprefilter : bool, default=False\n Apply spline pre-filter (= interpolates the input)\n\nReturns\n-------\noutput : (..., [channel], *shape, dim) tensor\n Sampled gradients.\n\"\"\"\n```\n\n```python\ninterpol.spline_coeff_nd(\n input,\n interpolation='linear',\n bound='dct2',\n dim=None,\n inplace=False,\n)\n\"\"\"\nCompute the interpolating spline coefficients, for a given spline order\nand boundary conditions, along the last `dim` dimensions.\n\nReferences\n----------\n..[1] M. Unser, A. Aldroubi and M. Eden.\n \"B-Spline Signal Processing: Part I-Theory,\"\n IEEE Transactions on Signal Processing 41(2):821-832 (1993).\n..[2] M. Unser, A. Aldroubi and M. Eden.\n \"B-Spline Signal Processing: Part II-Efficient Design and Applications,\"\n IEEE Transactions on Signal Processing 41(2):834-848 (1993).\n..[3] M. Unser.\n \"Splines: A Perfect Fit for Signal and Image Processing,\"\n IEEE Signal Processing Magazine 16(6):22-38 (1999).\n\nParameters\n----------\ninput : (..., *spatial) tensor\n Input image.\ninterpolation : int or sequence[int], default=1\n Interpolation order.\nbound : BoundType or sequence[BoundType], default='dct1'\n Boundary conditions.\ndim : int, default=-1\n Number of spatial dimensions\ninplace : bool, default=False\n Process the volume in place.\n\nReturns\n-------\noutput : (..., *spatial) tensor\n Coefficient image.\n\"\"\"\n```\n\n```python\ninterpol.resize(\n image, \n factor=None, \n shape=None, \n anchor='c',\n interpolation=1, \n prefilter=True\n)\n\"\"\"Resize an image by a factor or to a specific shape.\n\nNotes\n-----\n.. A least one of `factor` and `shape` must be specified\n.. If `anchor in ('centers', 'edges')`, exactly one of `factor` or\n `shape must be specified.\n.. If `anchor in ('first', 'last')`, `factor` must be provided even\n if `shape` is specified.\n.. Because of rounding, it is in general not assured that\n `resize(resize(x, f), 1/f)` returns a tensor with the same shape as x.\n\n edges centers first last\n e - + - + - e + - + - + - + + - + - + - + + - + - + - +\n | . | . | . | | c | . | c | | f | . | . | | . | . | . |\n + _ + _ + _ + + _ + _ + _ + + _ + _ + _ + + _ + _ + _ +\n | . | . | . | | . | . | . | | . | . | . | | . | . | . |\n + _ + _ + _ + + _ + _ + _ + + _ + _ + _ + + _ + _ + _ +\n | . | . | . | | c | . | c | | . | . | . | | . | . | l |\n e _ + _ + _ e + _ + _ + _ + + _ + _ + _ + + _ + _ + _ +\n\nParameters\n----------\nimage : (batch, channel, *inshape) tensor\n Image to resize\nfactor : float or list[float], optional\n Resizing factor\n * > 1 : larger image <-> smaller voxels\n * < 1 : smaller image <-> larger voxels\nshape : (ndim,) list[int], optional\n Output shape\nanchor : {'centers', 'edges', 'first', 'last'} or list, default='centers'\n * In cases 'c' and 'e', the volume shape is multiplied by the\n zoom factor (and eventually truncated), and two anchor points\n are used to determine the voxel size.\n * In cases 'f' and 'l', a single anchor point is used so that\n the voxel size is exactly divided by the zoom factor.\n This case with an integer factor corresponds to subslicing\n the volume (e.g., `vol[::f, ::f, ::f]`).\n * A list of anchors (one per dimension) can also be provided.\ninterpolation : int or sequence[int], default=1\n Interpolation order.\nprefilter : bool, default=True\n Apply spline pre-filter (= interpolates the input)\n\nReturns\n-------\nresized : (batch, channel, *shape) tensor\n Resized image\n\n\"\"\"\n```\n\n## License\n\ntorch-interpol is released under the MIT license.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "High-order spline interpolation in PyTorch",
"version": "0.2.6",
"project_urls": {
"Source Code": "https://github.com/balbasty/torch-interpol"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f25ca9c3ad572cb11191cfd15dae019f108df26b1cdb1556c7baa4cf68065524",
"md5": "1a493c8662298a184551f15ccd0285aa",
"sha256": "c583bf4790c4a1b083c9e28501e55c3cf93e5d974b95f09ef28f3378e73bec1b"
},
"downloads": -1,
"filename": "torch_interpol-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a493c8662298a184551f15ccd0285aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 37201,
"upload_time": "2024-09-13T08:04:37",
"upload_time_iso_8601": "2024-09-13T08:04:37.653497Z",
"url": "https://files.pythonhosted.org/packages/f2/5c/a9c3ad572cb11191cfd15dae019f108df26b1cdb1556c7baa4cf68065524/torch_interpol-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb36f2bcf9ba3de378532b007390356ca2bdd5649c5ab6d72595bf422d202c73",
"md5": "7decaaec21b7b014248a8b8b6d7e1765",
"sha256": "a3789aa83a1bd0eed2b05c0741a222b675e7c41bf9797ec246c167c1efeee577"
},
"downloads": -1,
"filename": "torch-interpol-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "7decaaec21b7b014248a8b8b6d7e1765",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 48454,
"upload_time": "2024-09-13T08:04:39",
"upload_time_iso_8601": "2024-09-13T08:04:39.145336Z",
"url": "https://files.pythonhosted.org/packages/cb/36/f2bcf9ba3de378532b007390356ca2bdd5649c5ab6d72595bf422d202c73/torch-interpol-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-13 08:04:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "balbasty",
"github_project": "torch-interpol",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "torch-interpol"
}
