astro-ndslice 0.2__tar.gz → 0.4__tar.gz

{astro-ndslice-0.2 → astro_ndslice-0.4}/.gitignore

@@ -1,3 +1,11 @@
+**/.DS_Store
+.claude/
+.cursor/
+.kiro/
+.handoff/
+.ruff_cache/
+.uv-cache/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

astro_ndslice-0.4/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## v0.4 (2026-11-12)
+
+### Fixes
+- **Image placement:** slice tuples work directly as NumPy indices. Canvas and
+  overlap sizes use the same rounded offsets, including half-pixel shifts.
+  - `offsets2slice(..., fits_convention=False)` returned lists of slices, causing
+    `array[indices[i]]` to raise `IndexError`. Now returns usable tuples.
+  - `offseted_shape(shapes=[(3,), (3,)], offsets=[(0,), (1.5,)])` returned `(4,)`.
+    Now returns `(5,)`, matching pixel placement.
+  - `offseted_shape(..., method="inner")` returned `(0,)` for touching images.
+    Now raises `ValueError` when there are no shared pixels.
+  - `offseted_shape(shapes=[(2.5,)], offsets=[(0,)])` silently rounded to `(2,)`.
+    Now raises `ValueError`.
+- **FITS conversion:** reverse slices retain their selected pixels;
+  unrepresentable slices raise `ValueError`.
+  - `slice(None, None, -1)` became `[:1]`, selecting only the first pixel.
+    Now becomes `[:1:-1]`, preserving the full reversal.
+  - `slice(2, 2)` became `[3:2]`, selecting two pixels instead of none.
+    Now raises `ValueError` when converting to FITS.
+- **WCS and headers:** coordinate arrays work. The default `ignore_ltm=False` applies
+  LTM scaling with a matrix solve; singular or invalid transforms raise
+  `ValueError`, including under `python -O`.
+  - `loc_target=np.array([2, 3])` raised an ambiguous-truth `ValueError`.
+    Now accepts coordinate arrays.
+  - `loc_target="center"` with unknown `WCS.pixel_shape` used zero dimensions.
+    Now raises `ValueError`.
+  - `LTV1=6, LTM1_1=2` returned `[6]` by default, ignoring scaling. Now returns
+    `[3.]`; `ignore_ltm=True` retains the raw value. Nonidentity LTM matrices
+    rejected by the earlier validation-only fix are now supported.
+- **Input helpers:** `listify()` broadcasts multiple inputs consistently;
+  `slicefy()` accepts generators; `bezel2slice(None)` returns full slices.
+- **Development:** explicit exports preserve public names. Development
+  dependencies include Astropy and isort.
+- **Releases:** Hatchling builds explicit package contents. CI tests installed
+  distributions. A matching `v*` tag push publishes the tested files to PyPI
+  after version, tag, changelog, lint, and test checks pass, then creates the
+  GitHub release from this changelog.
+
+### Migration checklist
+
+1. **LTM:** add `ignore_ltm=True` to retain raw LTV differences. The new default
+   applies LTM correction and rejects invalid transforms.
+2. **Image indices:** replace whole tuples from `offsets2slice()`; their elements
+   are no longer mutable.
+3. **Geometry:** use matching shapes/offsets, nonnegative integer sizes, and finite
+   offsets. Empty overlap raises `ValueError`; half-pixel canvas sizes may change.
+4. **FITS slices:** keep negative bounds and empty slices in Python form with
+   `fits_convention=False`.
+5. **WCS centers:** set `WCS.pixel_shape`, pass coordinates, or use `"origin"`.
+
+Also: `listify(..., scalar2list=False)` affects only single-input calls;
+`slicefy()` rejects empty iterable rules.
+Details: [offsets](astro_ndslice/offset.py), [slices](astro_ndslice/slices.py).

astro_ndslice-0.4/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: astro-ndslice
+Version: 0.4
+Summary: Convenience tools for slicing images & calculating offsets before combinations (focusing on converting astronomical FITS/IRAF and python conventions)
+Project-URL: Source, https://github.com/ysBach/astro-ndslice
+Project-URL: Tracker, https://github.com/ysBach/astro-ndslice/issues
+Author-email: "Yoonsoo P. Bach" <ysbach20766@gmail.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2023, Yoonsoo P. Bach
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: LICENSE
+Keywords: astronomy,data reduction,image analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Provides-Extra: dev
+Requires-Dist: astropy>=5.3.3; extra == 'dev'
+Requires-Dist: isort; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: astropy>=5.3.3; extra == 'full'
+Description-Content-Type: text/markdown
+
+# astro-ndslice
+
+[![DOI](https://zenodo.org/badge/601666411.svg)](https://zenodo.org/badge/latestdoi/601666411)
+
+Slice NumPy arrays, convert FITS/IRAF sections, and align images by pixel offsets.
+
+## Install
+
+```bash
+pip install astro-ndslice
+```
+
+Python >= 3.10.
+
+For astronomers who need WCS/header offset helpers:
+
+```bash
+pip install "astro-ndslice[full]"
+```
+
+## Slice an image
+
+```python
+import numpy as np
+from astro_ndslice import slicefy
+
+data = np.arange(100).reshape(10, 10)
+cutout = data[slicefy("[2:5,3:7]")]  # Same as data[2:7, 1:5].
+trimmed = data[slicefy(1)]          # Trim one pixel from each edge - bezeling.
+```
+
+* **FITS sections** use **1-based, inclusive bounds in x, y order**.
+* **NumPy** uses **0-based, exclusive stops in row, column order**.
+* `slicefy()` assumes FITS strings
+* `slice_from_string()` assumes Python strings unless you pass `fits_convention=True`.
+
+## Align images
+
+```python
+import numpy as np
+from astro_ndslice import offseted_shape, offsets2slice
+
+images = [np.ones((3, 4)), np.full((2, 3), 2)]
+shapes = [image.shape for image in images]  # NumPy axis order.
+offsets = [(0, 0), (2, 1)]                # x, y offsets.
+_, shape = offseted_shape(shapes, offsets)
+indices = offsets2slice(shapes, offsets)
+stack = np.full((len(images), *shape), np.nan)
+for image, index in zip(images, indices):
+    stack[index] = image
+```
+
+Both helpers round relative offsets to pixel positions. Use `method="inner"`
+to find the region shared by every image; no shared pixels raises `ValueError`.
+
+## Function guide
+
+| Task | Functions |
+| --- | --- |
+| Normalize scalars and iterables | `is_list_like`, `listify`, `ndfy` |
+| Parse sections and trim edges | `slicefy`, `slice_from_string`, `slice_to_string`, `bezel2slice` |
+| Place images and find overlap | `regularize_offsets`, `offseted_shape`, `offsets2slice` |
+| Read WCS or physical offsets | `calc_offset_wcs`, `calc_offset_physical` (requires Astropy) |
+
+`calc_offset_physical()` corrects LTV translation terms
+for LTM scaling in shared physical-coordinate units. For example,
+`LTV1=6, LTM1_1=2` gives `3` along x; `ignore_ltm=True` gives the raw value `6`.
+This preserves the LTV sign; differing LTM matrices require resampling for
+image alignment.
+
+See [CHANGELOG.md](CHANGELOG.md) for return-type changes and stricter validation.
+For version bumps and PyPI publishing, see [RELEASING.md](RELEASING.md).

astro_ndslice-0.4/README.md

@@ -0,0 +1,72 @@
+# astro-ndslice
+
+[![DOI](https://zenodo.org/badge/601666411.svg)](https://zenodo.org/badge/latestdoi/601666411)
+
+Slice NumPy arrays, convert FITS/IRAF sections, and align images by pixel offsets.
+
+## Install
+
+```bash
+pip install astro-ndslice
+```
+
+Python >= 3.10.
+
+For astronomers who need WCS/header offset helpers:
+
+```bash
+pip install "astro-ndslice[full]"
+```
+
+## Slice an image
+
+```python
+import numpy as np
+from astro_ndslice import slicefy
+
+data = np.arange(100).reshape(10, 10)
+cutout = data[slicefy("[2:5,3:7]")]  # Same as data[2:7, 1:5].
+trimmed = data[slicefy(1)]          # Trim one pixel from each edge - bezeling.
+```
+
+* **FITS sections** use **1-based, inclusive bounds in x, y order**.
+* **NumPy** uses **0-based, exclusive stops in row, column order**.
+* `slicefy()` assumes FITS strings
+* `slice_from_string()` assumes Python strings unless you pass `fits_convention=True`.
+
+## Align images
+
+```python
+import numpy as np
+from astro_ndslice import offseted_shape, offsets2slice
+
+images = [np.ones((3, 4)), np.full((2, 3), 2)]
+shapes = [image.shape for image in images]  # NumPy axis order.
+offsets = [(0, 0), (2, 1)]                # x, y offsets.
+_, shape = offseted_shape(shapes, offsets)
+indices = offsets2slice(shapes, offsets)
+stack = np.full((len(images), *shape), np.nan)
+for image, index in zip(images, indices):
+    stack[index] = image
+```
+
+Both helpers round relative offsets to pixel positions. Use `method="inner"`
+to find the region shared by every image; no shared pixels raises `ValueError`.
+
+## Function guide
+
+| Task | Functions |
+| --- | --- |
+| Normalize scalars and iterables | `is_list_like`, `listify`, `ndfy` |
+| Parse sections and trim edges | `slicefy`, `slice_from_string`, `slice_to_string`, `bezel2slice` |
+| Place images and find overlap | `regularize_offsets`, `offseted_shape`, `offsets2slice` |
+| Read WCS or physical offsets | `calc_offset_wcs`, `calc_offset_physical` (requires Astropy) |
+
+`calc_offset_physical()` corrects LTV translation terms
+for LTM scaling in shared physical-coordinate units. For example,
+`LTV1=6, LTM1_1=2` gives `3` along x; `ignore_ltm=True` gives the raw value `6`.
+This preserves the LTV sign; differing LTM matrices require resampling for
+image alignment.
+
+See [CHANGELOG.md](CHANGELOG.md) for return-type changes and stricter validation.
+For version bumps and PyPI publishing, see [RELEASING.md](RELEASING.md).

astro_ndslice-0.4/RELEASING.md

@@ -0,0 +1,94 @@
+# Release astro-ndslice
+
+**Push a matching `vX.Y.Z` tag to validate, publish to PyPI, and create the
+GitHub release.** Manual workflow runs validate only and never upload.
+
+| Event | Checks | Publication |
+| --- | --- | --- |
+| Push to `main` or pull request | CI and installed distributions | None |
+| Manual **Release → Run workflow** | Same checks, plus dated release notes | None |
+| Matching `v{version}` tag push | Same checks, plus tag match | PyPI, then GitHub release |
+
+Do not create the GitHub release by hand. The workflow creates it after the
+PyPI upload succeeds, with the matching `CHANGELOG.md` section as its notes.
+
+## One-time setup
+
+1. In GitHub **Settings → Environments**, create an environment named `pypi`.
+   Restrict its deployment to tags that match `v*`.
+2. In [PyPI Publishing settings](https://pypi.org/manage/project/astro-ndslice/settings/publishing/),
+   add (or edit) the trusted publisher:
+
+   | Setting | Value |
+   | --- | --- |
+   | Owner / repository | `ysBach` / `astro-ndslice` |
+   | Workflow | `release.yml` |
+   | Environment | `pypi` |
+
+Only the upload job receives `id-token: write`; no API token is needed.
+See [PyPI's setup guide](https://docs.pypi.org/trusted-publishers/adding-a-publisher/).
+
+## Each release
+
+Use one Bash/zsh session in the repository root, with `uv` and authenticated `gh`.
+Commit or merge the intended changes onto `main` first.
+
+1. **Set the version.** Replace `1.2.3` with the intended release version.
+
+   ```bash
+   release_version=1.2.3
+   git switch main &&
+   uv version "$release_version" --no-sync
+   ```
+
+   `pyproject.toml` is the version source; this also updates `uv.lock` without
+   syncing any environment. No separate Python version constant is maintained.
+
+2. **Date the release notes.** Rename `## Unreleased` in `CHANGELOG.md` to
+   `## v1.2.3 (YYYY-MM-DD)`, using the version above and actual release date.
+   Keep this release's bullets below it. Validate with the project `.venv`:
+
+   ```bash
+   uv sync --locked --python 3.13 &&
+   uv run --no-sync python .github/scripts/check_release.py \
+     --release --tag "v$release_version"
+   ```
+
+3. **Commit and push.**
+
+   ```bash
+   git add pyproject.toml uv.lock CHANGELOG.md &&
+   git commit -m "chore: prepare release $release_version" &&
+   git push origin main
+   ```
+
+4. **Wait for CI** on that commit in
+   [GitHub Actions](https://github.com/ysBach/astro-ndslice/actions).
+   Optional rehearsal: `gh workflow run release.yml --ref main`. It runs the
+   release checks but never uploads.
+
+5. **Tag that commit and push the tag.** The tag must be exactly
+   `v{version}`, for example `v1.2.3`. The older `v.0.2` style fails validation.
+
+   ```bash
+   git tag -a "v$release_version" -m "Release $release_version" &&
+   git push origin "v$release_version"
+   ```
+
+   Check the **Release** run in Actions, the version on
+   [PyPI](https://pypi.org/project/astro-ndslice/), and the new GitHub release.
+
+## Validation
+
+- Package and lockfile versions must match. Releases also require a matching
+  `v{version}` tag and a dated, nonempty changelog entry.
+- Hatchling builds one universal wheel and one sdist with `uv build --no-sources`.
+- CI tests installed wheels on Python 3.10–3.14 and the sdist on Python 3.13,
+  outside the checkout. Astropy tests, docstrings, formatting, and lint must pass.
+- Publishing uploads those tested artifacts, without rebuilding. The sdist
+  includes tests and public docs; local files and workflows are excluded.
+
+If nothing uploaded, fix the cause and rerun failed jobs. `uv publish
+--check-url` skips files that PyPI already has, so a rerun after a partial
+upload sends only the missing files. Published files cannot be replaced;
+source fixes need a new version and tag. Do not move a published tag.

astro_ndslice-0.4/astro_ndslice/__init__.py

@@ -0,0 +1,28 @@
+from . import lists, offset, slices
+from .lists import is_list_like, listify, ndfy
+from .offset import (
+    calc_offset_physical,
+    calc_offset_wcs,
+    offseted_shape,
+    offsets2slice,
+    regularize_offsets,
+)
+from .slices import bezel2slice, slice_from_string, slice_to_string, slicefy
+
+__all__ = [
+    "lists",
+    "offset",
+    "slices",
+    "is_list_like",
+    "listify",
+    "ndfy",
+    "regularize_offsets",
+    "offseted_shape",
+    "offsets2slice",
+    "calc_offset_wcs",
+    "calc_offset_physical",
+    "slice_from_string",
+    "slice_to_string",
+    "slicefy",
+    "bezel2slice",
+]

astro_ndslice-0.4/astro_ndslice/lists.py

@@ -0,0 +1,192 @@
+"""Normalize scalars and iterables to lists."""
+
+from collections import abc
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+__all__ = [
+    "is_list_like",
+    "listify",
+    "ndfy",
+]
+
+
+def is_list_like(*objs, allow_sets: bool = True, func: Callable = all) -> bool:
+    """Check whether inputs are iterable, excluding strings and scalar arrays.
+
+    Parameters
+    ----------
+    *objs : object
+        Objects to check.
+    allow_sets : bool, optional
+        Count sets as list-like. Default: `True`.
+    func : callable, optional
+        Combine results with `all` (default), `any`, or another callable.
+
+    Returns
+    -------
+    bool or object
+        Result from `func`; `all` and `any` return a boolean. Strings, bytes,
+        and zero-dimensional arrays are not list-like. Other iterables,
+        including dictionaries, are.
+
+    Notes
+    -----
+    Adapted from pandas to accept multiple inputs and a combining function.
+    https://github.com/pandas-dev/pandas/blob/bdb00f2d5a12f813e93bc55cdcd56dcb1aae776e/pandas/_libs/lib.pyx#L1026
+
+    Timing on MBP 14" [2024, macOS 26.6, M4Pro(8P+4E/G20c/N16c/48G)]
+    (2026-09-07; CPython 3.13.11, NumPy 2.5.2)::
+
+        is_list_like("asdfaer.fits")  0.188 +/- 0.001 us
+
+    Mean +/- std. dev. per call (`timeit`, 7 runs, 2,000,000 loops each).
+    """
+
+    def _is_list_like(obj):
+        return (
+            isinstance(obj, abc.Iterable)
+            # we do not count strings/unicode/bytes as list-like
+            and not isinstance(obj, (str, bytes))
+            # exclude zero-dimensional numpy arrays, effectively scalars
+            and not (isinstance(obj, np.ndarray) and obj.ndim == 0)
+            # exclude sets if allow_sets is False
+            and not (allow_sets is False and isinstance(obj, abc.Set))
+        )
+
+    if func is all:
+        for obj in objs:
+            if not _is_list_like(obj):
+                return False
+        return True
+    if func is any:
+        for obj in objs:
+            if _is_list_like(obj):
+                return True
+        return False
+
+    return func(_is_list_like(obj) for obj in objs)
+
+
+def listify(*objs: Any, scalar2list: bool = True, none2list: bool = False) -> Any:
+    """Convert inputs to lists of the same length.
+
+    Parameters
+    ----------
+    *objs : object
+        One or more inputs. Iterables become lists; strings count as scalars.
+        With multiple inputs, length-one lists and scalars are repeated to
+        match the longest input.
+    scalar2list : bool, optional
+        Wrap a single scalar in a list. Ignored for multiple inputs and
+        iterable inputs. Default: `True`.
+    none2list : bool, optional
+        Return ``[None]`` for a single `None`, instead of ``[]``.
+        With multiple inputs, `None` always becomes a length-one list before
+        broadcasting. Default: `False`.
+
+    Returns
+    -------
+    list or object
+        Normalized lists, or the original single scalar when `scalar2list`
+        is `False`.
+
+    Raises
+    ------
+    ValueError
+        If no inputs are given or input lengths cannot be broadcast.
+
+    Notes
+    -----
+    Timing on MBP 14" [2024, macOS 26.6, M4Pro(8P+4E/G20c/N16c/48G)]
+    (2026-09-07; CPython 3.13.11, NumPy 2.5.2)::
+
+        listify([12])                         0.331 +/- 0.003 us
+        listify("asdf")                       0.249 +/- 0.001 us
+        listify("asdf", scalar2list=False)     0.238 +/- 0.001 us
+
+    Mean +/- std. dev. per call (`timeit`, 7 runs, 1,000,000 loops each).
+
+    Examples
+    --------
+    >>> listify([1, 2], "x", None)
+    [[1, 2], ['x', 'x'], [None, None]]
+    >>> listify(3, scalar2list=False)
+    3
+    """
+
+    if len(objs) == 1:
+        obj = objs[0]
+        if obj is None:
+            return [None] if none2list else []
+        if is_list_like(obj):
+            return list(obj)
+        return [obj] if scalar2list else obj
+
+    objlists = [list(obj) if is_list_like(obj) else [obj] for obj in objs]
+    lengths = [len(obj) for obj in objlists]
+    length = max(lengths)
+    for objl in objlists:
+        if len(objl) not in [1, length]:
+            raise ValueError(f"Each input must be 1 or max(lengths)={length}.")
+
+    return [obj * length if len(obj) == 1 else obj for obj in objlists]
+
+
+def ndfy(item, length: int | None = None, default: Any = None) -> list:
+    """Normalize a list, replace `None`, and repeat a single item as needed.
+
+    Parameters
+    ----------
+    item : object
+        Scalar or iterable to normalize.
+    length : int, optional
+        Target length; a single item repeats, other lengths must match.
+        `None` keeps the input length, or one for a scalar.
+    default : object, optional
+        Replacement for a `None` input or top-level element. Default: `None`.
+
+    Returns
+    -------
+    list
+        Normalized values. Nested inputs are preserved, not transposed.
+
+    Raises
+    ------
+    ValueError
+        If the input length is neither one nor the requested length.
+
+    Notes
+    -----
+    Repetition reuses references; nested mutable values are not copied.
+
+    Timing on MBP 14" [2024, macOS 26.6, M4Pro(8P+4E/G20c/N16c/48G)]
+    (2026-09-07; CPython 3.13.11, NumPy 2.4.6)::
+
+        ndfy(1, length=2)  0.356 +/- 0.004 us
+        ndfy([1, None], default=0)  0.426 +/- 0.010 us
+
+    Mean +/- std. dev. per call (`timeit`, 7 runs;
+    1,000,000/500,000 loops in row order).
+
+    Examples
+    --------
+    >>> ndfy(None, length=2, default=0)
+    [0, 0]
+    >>> ndfy([[1, 2]], length=2)
+    [[1, 2], [1, 2]]
+    """
+    item = [default if i is None else i for i in listify(item, none2list=True)]
+    item_length = len(item)
+
+    if (length is None) or (item_length == length):
+        return item
+    elif item_length != 1:
+        raise ValueError(
+            f"`len(item)` must be 1 or `length`(={length}). Now it is {item_length}."
+        )
+
+    # Now, item_length == 1
+    return item * length