py4D-browser-transform 0.0.2__tar.gz → 0.1.0__tar.gz

py4d_browser_transform-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: py4D-browser-transform
+Version: 0.1.0
+Summary: py4D-browser plugin that adds utility functions which transform the datacube
+Author-email: Chia-Hao Lee <chia-hao.lee@cornell.edu>
+Project-URL: Homepage, https://github.com/chiahao3/py4D-browser-transform
+Project-URL: Repository, https://github.com/chiahao3/py4D-browser-transform
+Project-URL: Bug Tracker, https://github.com/chiahao3/py4D-browser-transform/issues
+Project-URL: Changelog, https://github.com/chiahao3/py4D-browser-transform/blob/main/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: py4d-browser>=1.5.0
+Requires-Dist: py4dstem>=0.14.9
+Requires-Dist: numpy>=1.19
+Dynamic: license-file
+
+# py4D-browser-transform
+
+`py4D-browser-transform` is a plugin for [py4D-browser](https://github.com/sezelt/py4D-browser) that adds in-memory datacube transformation tools. It currently supports axis permutation, diffraction flips/transposes, RAM checkpoints and restore, and datacube slicing, subsampling, and binning.
+
+## Installation
+You can install `py4D-browser-transform` with pip or conda:
+
+```bash
+pip install py4d-browser-transform
+```
+
+> 💡 **Note:** 
+> - If you install into a fresh Python environment, `py4D-browser` and `py4DSTEM` will be automatically installed as dependencies so you don't need to install them first.
+> - If you already have `py4D-browser` installed, you can install this plugin into the same Python environment.
+
+A step-by-step guide including creating a fresh Python environment via conda would look like this:
+```bash
+conda create -n py4dgui python=3.12
+conda activate py4dgui
+python -m pip install --upgrade pip
+python -m pip cache purge
+pip install py4d-browser-transform
+```
+
+## Usage
+Simply run the following command to start the browser once you activated the corresponding Python environment:
+
+```bash
+py4dgui
+```
+
+After installing this plugin, you should see the "Transform" submenu appear under the **"Plugins"** menu.  
+From here, you can:
+
+- **Set Axis Permutation**: reorder the four datacube axes when the loaded dataset is not in the expected order.
+- **Set Diffraction Flips**: flip the diffraction pattern up/down, left/right, or transpose its X/Y axes.
+- **Save RAM Checkpoint**: store a RAM-only snapshot of the current in-memory datacube.
+- **Restore RAM Checkpoint**: restore a previous RAM checkpoint, rename checkpoints, replace checkpoints, or delete checkpoints.
+- **Slice / Subsample / Bin**: slice, subsample with Python-style step syntax such as `::2`, and bin along the displayed axes `Ry`, `Rx`, `Qy`, and `Qx`.
+
+![Demo of py4D-browser-transform](assets/demo.gif)
+
+These operations directly modify the loaded in-memory datacube, but do not affect the raw file stored on disk. You can export the transformed datacube to disk using **File > Export Datacube**.
+
+### RAM checkpoints
+
+RAM checkpoints are session-local snapshots of the datacube data at the moment they are saved. They are intended as recovery points before destructive in-memory transformations such as slicing, subsampling, and binning.
+
+Checkpoint restore loads the saved datacube snapshot and resets the flip/permutation markers back to their default clean state. In other words, a checkpoint represents "the datacube exactly as it looked then", not a reversible history of every flip or permutation action that produced it.
+
+Large checkpoints can require substantial memory. The plugin warns before saving a checkpoint larger than 1 GiB, or when total stored checkpoint data would exceed 4 GiB.
+
+### Slicing, subsampling, and binning
+
+The **Slice / Subsample / Bin** dialog provides one row for each axis:
+
+- `Ry`
+- `Rx`
+- `Qy`
+- `Qx`
+
+Use slice text like `:`, `10:100`, or `::4` to select or subsample data. Use the bin control to sum neighboring pixels along an axis. The dialog previews the output shape before applying the transform.
+
+Calibration pixel sizes are updated when both axes in real space or both axes in diffraction space change by the same spacing factor. When the change cannot be represented safely by py4DSTEM's shared real-space or diffraction-space pixel size, calibration is preserved.
+
+> **Note:**
+> The order of flipping and permutation matters. If you mix these operations, reversing them manually requires applying the opposite operations in the opposite order. RAM checkpoints provide a simpler way to return to a known datacube state.
+
+## License
+
+GNU GPLv3
+
+**py4D-browser-transform** is open source software distributed under a GPLv3 license.
+It is free to use, alter, or build on, provided that any work derived from **py4D-browser-transform** is also kept free and open.

py4d_browser_transform-0.1.0/README.md

@@ -0,0 +1,74 @@
+# py4D-browser-transform
+
+`py4D-browser-transform` is a plugin for [py4D-browser](https://github.com/sezelt/py4D-browser) that adds in-memory datacube transformation tools. It currently supports axis permutation, diffraction flips/transposes, RAM checkpoints and restore, and datacube slicing, subsampling, and binning.
+
+## Installation
+You can install `py4D-browser-transform` with pip or conda:
+
+```bash
+pip install py4d-browser-transform
+```
+
+> 💡 **Note:** 
+> - If you install into a fresh Python environment, `py4D-browser` and `py4DSTEM` will be automatically installed as dependencies so you don't need to install them first.
+> - If you already have `py4D-browser` installed, you can install this plugin into the same Python environment.
+
+A step-by-step guide including creating a fresh Python environment via conda would look like this:
+```bash
+conda create -n py4dgui python=3.12
+conda activate py4dgui
+python -m pip install --upgrade pip
+python -m pip cache purge
+pip install py4d-browser-transform
+```
+
+## Usage
+Simply run the following command to start the browser once you activated the corresponding Python environment:
+
+```bash
+py4dgui
+```
+
+After installing this plugin, you should see the "Transform" submenu appear under the **"Plugins"** menu.  
+From here, you can:
+
+- **Set Axis Permutation**: reorder the four datacube axes when the loaded dataset is not in the expected order.
+- **Set Diffraction Flips**: flip the diffraction pattern up/down, left/right, or transpose its X/Y axes.
+- **Save RAM Checkpoint**: store a RAM-only snapshot of the current in-memory datacube.
+- **Restore RAM Checkpoint**: restore a previous RAM checkpoint, rename checkpoints, replace checkpoints, or delete checkpoints.
+- **Slice / Subsample / Bin**: slice, subsample with Python-style step syntax such as `::2`, and bin along the displayed axes `Ry`, `Rx`, `Qy`, and `Qx`.
+
+![Demo of py4D-browser-transform](assets/demo.gif)
+
+These operations directly modify the loaded in-memory datacube, but do not affect the raw file stored on disk. You can export the transformed datacube to disk using **File > Export Datacube**.
+
+### RAM checkpoints
+
+RAM checkpoints are session-local snapshots of the datacube data at the moment they are saved. They are intended as recovery points before destructive in-memory transformations such as slicing, subsampling, and binning.
+
+Checkpoint restore loads the saved datacube snapshot and resets the flip/permutation markers back to their default clean state. In other words, a checkpoint represents "the datacube exactly as it looked then", not a reversible history of every flip or permutation action that produced it.
+
+Large checkpoints can require substantial memory. The plugin warns before saving a checkpoint larger than 1 GiB, or when total stored checkpoint data would exceed 4 GiB.
+
+### Slicing, subsampling, and binning
+
+The **Slice / Subsample / Bin** dialog provides one row for each axis:
+
+- `Ry`
+- `Rx`
+- `Qy`
+- `Qx`
+
+Use slice text like `:`, `10:100`, or `::4` to select or subsample data. Use the bin control to sum neighboring pixels along an axis. The dialog previews the output shape before applying the transform.
+
+Calibration pixel sizes are updated when both axes in real space or both axes in diffraction space change by the same spacing factor. When the change cannot be represented safely by py4DSTEM's shared real-space or diffraction-space pixel size, calibration is preserved.
+
+> **Note:**
+> The order of flipping and permutation matters. If you mix these operations, reversing them manually requires applying the opposite operations in the opposite order. RAM checkpoints provide a simpler way to return to a known datacube state.
+
+## License
+
+GNU GPLv3
+
+**py4D-browser-transform** is open source software distributed under a GPLv3 license.
+It is free to use, alter, or build on, provided that any work derived from **py4D-browser-transform** is also kept free and open.

{py4d_browser_transform-0.0.2 → py4d_browser_transform-0.1.0}/pyproject.toml

@@ -10,7 +10,7 @@ authors = [
 ]
 description = "py4D-browser plugin that adds utility functions which transform the datacube"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 classifiers = [
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",

py4d_browser_transform-0.1.0/src/py4D_browser_transform.egg-info/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: py4D-browser-transform
+Version: 0.1.0
+Summary: py4D-browser plugin that adds utility functions which transform the datacube
+Author-email: Chia-Hao Lee <chia-hao.lee@cornell.edu>
+Project-URL: Homepage, https://github.com/chiahao3/py4D-browser-transform
+Project-URL: Repository, https://github.com/chiahao3/py4D-browser-transform
+Project-URL: Bug Tracker, https://github.com/chiahao3/py4D-browser-transform/issues
+Project-URL: Changelog, https://github.com/chiahao3/py4D-browser-transform/blob/main/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: py4d-browser>=1.5.0
+Requires-Dist: py4dstem>=0.14.9
+Requires-Dist: numpy>=1.19
+Dynamic: license-file
+
+# py4D-browser-transform
+
+`py4D-browser-transform` is a plugin for [py4D-browser](https://github.com/sezelt/py4D-browser) that adds in-memory datacube transformation tools. It currently supports axis permutation, diffraction flips/transposes, RAM checkpoints and restore, and datacube slicing, subsampling, and binning.
+
+## Installation
+You can install `py4D-browser-transform` with pip or conda:
+
+```bash
+pip install py4d-browser-transform
+```
+
+> 💡 **Note:** 
+> - If you install into a fresh Python environment, `py4D-browser` and `py4DSTEM` will be automatically installed as dependencies so you don't need to install them first.
+> - If you already have `py4D-browser` installed, you can install this plugin into the same Python environment.
+
+A step-by-step guide including creating a fresh Python environment via conda would look like this:
+```bash
+conda create -n py4dgui python=3.12
+conda activate py4dgui
+python -m pip install --upgrade pip
+python -m pip cache purge
+pip install py4d-browser-transform
+```
+
+## Usage
+Simply run the following command to start the browser once you activated the corresponding Python environment:
+
+```bash
+py4dgui
+```
+
+After installing this plugin, you should see the "Transform" submenu appear under the **"Plugins"** menu.  
+From here, you can:
+
+- **Set Axis Permutation**: reorder the four datacube axes when the loaded dataset is not in the expected order.
+- **Set Diffraction Flips**: flip the diffraction pattern up/down, left/right, or transpose its X/Y axes.
+- **Save RAM Checkpoint**: store a RAM-only snapshot of the current in-memory datacube.
+- **Restore RAM Checkpoint**: restore a previous RAM checkpoint, rename checkpoints, replace checkpoints, or delete checkpoints.
+- **Slice / Subsample / Bin**: slice, subsample with Python-style step syntax such as `::2`, and bin along the displayed axes `Ry`, `Rx`, `Qy`, and `Qx`.
+
+![Demo of py4D-browser-transform](assets/demo.gif)
+
+These operations directly modify the loaded in-memory datacube, but do not affect the raw file stored on disk. You can export the transformed datacube to disk using **File > Export Datacube**.
+
+### RAM checkpoints
+
+RAM checkpoints are session-local snapshots of the datacube data at the moment they are saved. They are intended as recovery points before destructive in-memory transformations such as slicing, subsampling, and binning.
+
+Checkpoint restore loads the saved datacube snapshot and resets the flip/permutation markers back to their default clean state. In other words, a checkpoint represents "the datacube exactly as it looked then", not a reversible history of every flip or permutation action that produced it.
+
+Large checkpoints can require substantial memory. The plugin warns before saving a checkpoint larger than 1 GiB, or when total stored checkpoint data would exceed 4 GiB.
+
+### Slicing, subsampling, and binning
+
+The **Slice / Subsample / Bin** dialog provides one row for each axis:
+
+- `Ry`
+- `Rx`
+- `Qy`
+- `Qx`
+
+Use slice text like `:`, `10:100`, or `::4` to select or subsample data. Use the bin control to sum neighboring pixels along an axis. The dialog previews the output shape before applying the transform.
+
+Calibration pixel sizes are updated when both axes in real space or both axes in diffraction space change by the same spacing factor. When the change cannot be represented safely by py4DSTEM's shared real-space or diffraction-space pixel size, calibration is preserved.
+
+> **Note:**
+> The order of flipping and permutation matters. If you mix these operations, reversing them manually requires applying the opposite operations in the opposite order. RAM checkpoints provide a simpler way to return to a known datacube state.
+
+## License
+
+GNU GPLv3
+
+**py4D-browser-transform** is open source software distributed under a GPLv3 license.
+It is free to use, alter, or build on, provided that any work derived from **py4D-browser-transform** is also kept free and open.

{py4d_browser_transform-0.0.2 → py4d_browser_transform-0.1.0}/src/py4D_browser_transform.egg-info/SOURCES.txt

@@ -7,4 +7,8 @@ src/py4D_browser_transform.egg-info/dependency_links.txt
 src/py4D_browser_transform.egg-info/requires.txt
 src/py4D_browser_transform.egg-info/top_level.txt
 src/py4d_browser_plugin/transform/__init__.py
-src/py4d_browser_plugin/transform/transform.py
+src/py4d_browser_plugin/transform/checkpoints.py
+src/py4d_browser_plugin/transform/datacube_ops.py
+src/py4d_browser_plugin/transform/dialogs.py
+src/py4d_browser_plugin/transform/transform.py
+tests/test_transform_datacube_updates.py

{py4d_browser_transform-0.0.2 → py4d_browser_transform-0.1.0}/src/py4d_browser_plugin/transform/__init__.py

@@ -1,2 +1,2 @@
 from .transform import TransformPlugin
-__version__ = '0.0.2' # 2026.05.06
+__version__ = '0.1.0' # 2026.05.23

py4d_browser_transform-0.1.0/src/py4d_browser_plugin/transform/checkpoints.py

@@ -0,0 +1,51 @@
+"""RAM checkpoint records and datacube snapshot helpers."""
+
+from dataclasses import dataclass
+
+
+CHECKPOINT_WARNING_BYTES = 1024**3
+CHECKPOINT_TOTAL_WARNING_BYTES = 4 * 1024**3
+
+
+@dataclass
+class DatacubeCheckpoint:
+    checkpoint_id: int
+    name: str
+    created_at: object
+    shape: tuple
+    dtype: str
+    estimated_bytes: int
+    datacube: object
+    metadata: dict
+    window_title: str
+
+
+def copy_datacube(datacube):
+    if hasattr(datacube, "copy"):
+        return datacube.copy()
+    copied = type(datacube)(datacube.data.copy())
+    if hasattr(datacube, "calibration"):
+        copied.calibration = datacube.calibration.copy()
+    return copied
+
+
+def datacube_nbytes(datacube):
+    return int(getattr(datacube.data, "nbytes", 0))
+
+
+def format_bytes(nbytes):
+    value = float(nbytes)
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+        if value < 1024 or unit == "TiB":
+            if unit == "B":
+                return f"{int(value)} {unit}"
+            return f"{value:.1f} {unit}"
+        value /= 1024
+
+
+def checkpoint_metadata(datacube):
+    return {
+        "shape": tuple(datacube.data.shape),
+        "dtype": str(datacube.data.dtype),
+        "estimated_bytes": datacube_nbytes(datacube),
+    }

py4d_browser_transform-0.1.0/src/py4d_browser_plugin/transform/datacube_ops.py

@@ -0,0 +1,147 @@
+"""Pure datacube slicing, subsampling, binning, and calibration helpers."""
+
+from .checkpoints import copy_datacube
+
+
+AXIS_LABELS = ("Ry", "Rx", "Qy", "Qx")
+
+
+def _parse_slice(text):
+    text = text.strip()
+    if text in ("", ":"):
+        return slice(None)
+    if text.startswith("[") and text.endswith("]"):
+        text = text[1:-1].strip()
+    if ":" not in text:
+        index = int(text)
+        return slice(index, index + 1, 1)
+    parts = text.split(":")
+    if len(parts) > 3:
+        raise ValueError(f"Invalid slice syntax: {text!r}")
+
+    values = []
+    for part in parts:
+        values.append(None if part.strip() == "" else int(part))
+    values.extend([None] * (3 - len(values)))
+    result = slice(values[0], values[1], values[2])
+    if result.step is not None and result.step <= 0:
+        raise ValueError("Slice steps must be positive")
+    return result
+
+
+def _bin_axis(data, axis, factor):
+    if factor <= 1:
+        return data
+    length = data.shape[axis]
+    usable = length - (length % factor)
+    if usable <= 0:
+        raise ValueError(
+            f"Axis {AXIS_LABELS[axis]} with length {length} is too small for bin {factor}"
+        )
+    if usable != length:
+        data = data[
+            tuple(
+                slice(0, usable) if i == axis else slice(None)
+                for i in range(data.ndim)
+            )
+        ]
+    shape = list(data.shape)
+    shape[axis : axis + 1] = [usable // factor, factor]
+    return data.reshape(shape).sum(axis=axis + 1)
+
+
+def _set_calibration_value(calibration, setter_name, value):
+    if value is None:
+        return
+    setter = getattr(calibration, setter_name, None)
+    if setter is not None:
+        setter(value)
+
+
+def _update_transform_calibration(datacube, starts, spacing_factors):
+    calibration = getattr(datacube, "calibration", None)
+    if calibration is None:
+        return
+
+    real_factors = (spacing_factors[0], spacing_factors[1])
+    if real_factors[0] == real_factors[1] and real_factors[0] != 1:
+        pixel_size = calibration.get_R_pixel_size()
+        _set_calibration_value(
+            calibration, "set_R_pixel_size", pixel_size * real_factors[0]
+        )
+
+    q_factors = (spacing_factors[2], spacing_factors[3])
+    old_q_pixel_size = calibration.get_Q_pixel_size()
+    if q_factors[0] == q_factors[1] and q_factors[0] != 1:
+        _set_calibration_value(
+            calibration, "set_Q_pixel_size", old_q_pixel_size * q_factors[0]
+        )
+
+    origin = calibration.get_origin() if hasattr(calibration, "get_origin") else None
+    if origin is not None and old_q_pixel_size is not None:
+        qx0, qy0 = origin
+        if qx0 is not None and qy0 is not None:
+            calibration.set_origin(
+                (
+                    qx0 - starts[2] * old_q_pixel_size,
+                    qy0 - starts[3] * old_q_pixel_size,
+                )
+            )
+
+
+def apply_datacube_operations(datacube, operations):
+    """Apply validated slice/subsample/bin operations to a copied datacube."""
+    if len(operations) != 4:
+        raise ValueError("Expected one operation for each of the four datacube axes")
+
+    slices = []
+    starts = []
+    spacing_factors = []
+    bins = []
+    shape = datacube.data.shape
+    if len(shape) != 4:
+        raise ValueError(f"Expected a 4D datacube, got shape {shape}")
+
+    for axis, operation in enumerate(operations):
+        axis_slice = _parse_slice(operation.get("slice", ":"))
+        start, stop, step = axis_slice.indices(shape[axis])
+        if stop <= start:
+            raise ValueError(f"Axis {AXIS_LABELS[axis]} slice selects no data")
+        bin_factor = int(operation.get("bin", 1))
+        if bin_factor < 1:
+            raise ValueError(f"Axis {AXIS_LABELS[axis]} bin factor must be positive")
+        slices.append(slice(start, stop, step))
+        starts.append(start)
+        spacing_factors.append(step * bin_factor)
+        bins.append(bin_factor)
+
+    transformed = copy_datacube(datacube)
+    transformed.data = transformed.data[tuple(slices)].copy()
+    for axis, bin_factor in enumerate(bins):
+        transformed.data = _bin_axis(transformed.data, axis, bin_factor)
+
+    _update_transform_calibration(transformed, starts, spacing_factors)
+    if hasattr(transformed, "calibrate"):
+        transformed.calibrate()
+    return transformed
+
+
+def estimate_transformed_shape(shape, operations):
+    transformed_shape = list(shape)
+    for axis, operation in enumerate(operations):
+        axis_slice = _parse_slice(operation.get("slice", ":"))
+        start, stop, step = axis_slice.indices(transformed_shape[axis])
+        if stop <= start:
+            raise ValueError(f"Axis {AXIS_LABELS[axis]} slice selects no data")
+        transformed_shape[axis] = len(range(start, stop, step))
+        bin_factor = int(operation.get("bin", 1))
+        if bin_factor < 1:
+            raise ValueError(f"Axis {AXIS_LABELS[axis]} bin factor must be positive")
+        if bin_factor > 1:
+            usable = transformed_shape[axis] - (transformed_shape[axis] % bin_factor)
+            if usable <= 0:
+                raise ValueError(
+                    f"Axis {AXIS_LABELS[axis]} with length {transformed_shape[axis]} is too small for bin {bin_factor}"
+                )
+            transformed_shape[axis] = usable // bin_factor
+    return tuple(transformed_shape)