Rhapso 0.1.95__py3-none-any.whl → 0.1.96__py3-none-any.whl

{rhapso-0.1.95.dist-info → rhapso-0.1.96.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Rhapso
-Version: 0.1.95
+Version: 0.1.96
 Summary: A python package for aligning and stitching light sheet fluorescence microscopy images together
 Author: ND
 Author-email: sean.fite@alleninstitute.org
@@ -46,10 +46,10 @@ Dynamic: summary
 
 # Rhapso
 
-**Rhapso** is a modular Python toolkit for interest point based registration, alignment, and fusing of large-scale microscopy datasets. 
+This is the code base for **Rhapso**, a modular Python toolkit for the alignment and stitching of large-scale microscopy datasets. 
 
 [![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
-[![Python Version](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3110/)
+[![Python Version](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3100/)
 [![Documentation](https://img.shields.io/badge/docs-wiki-blue)](https://github.com/AllenNeuralDynamics/Rhapso/wiki)
 
 <!-- ## Example Usage Media Content Coming Soon....
@@ -60,7 +60,7 @@ Dynamic: summary
 ## Table of Contents
 - [Summary](#summary)
 - [Contact](#contact)
-- [Features](#features)
+- [Supported Features](#supported-features)
 - [Performance](#performance)
 - [Layout](#layout)
 - [Installation](#installation)
@@ -77,7 +77,7 @@ Dynamic: summary
 
 <br>
 
-**Update 11/26/25** 
+**Update 1/12/26** 
 --------
 Rhapso is still loading... and while we wrap up development, a couple things to know if you are outside the Allen Institute: 
    - This process requires a very specific XML structure to work.
@@ -86,11 +86,15 @@ Rhapso is still loading... and while we wrap up development, a couple things to
 <br>
 
 ## Summary
-Rhapso is a set of Python components for registration, alignment, and stitching of large-scale, 3D, overlapping tile-based, multiscale microscopy datasets.
+Rhapso is a set of Python components used to register, align, and stitch large-scale, 3D, overlapping, tile-based, multiscale microscopy datasets. Its stateless components can run on a single machine or scale out across cloud-based clusters. 
 
-Rhapso was developed by the Allen Institute for Neural Dynamics. Rhapso is comprised of stateless components. You can call these components using a pipeline script, with the option to run on a single machine or scale out with Ray to cloud based (currently only supporting AWS) clusters.
+Rhapso is published on PyPI and can be installed with:
 
-Current data loaders support Zarr and Tiff.
+```bash
+pip install Rhapso
+```
+
+Rhapso was developed by the Allen Institute for Neural Dynamics.
 
 <br>
 
@@ -99,11 +103,15 @@ Questions or want to contribute? Please open an issue..
 
 <br>
 
-## Features
-- **Interest Point Detection** - using DOG based feature detection
-- **Interest Point Matching** - using descriptor based RANSAC to match feature points
-- **Global Optimization** - aligning matched features per tile, globally
-- **Validation and Visualization Tools** - validate component specific results for the best output
+## Supported Features
+- **Interest Point Detection** - DOG based feature detection
+- **Interest Point Matching** - Descriptor based RANSAC to match feature points
+- **Global Optimization** - Align matched features between tile pairs globally
+- **Validation and Visualization Tools** - Validate component specific results for the best output
+- **ZARR** - Zarr data as input
+- **TIFF** - Tiff data as input
+- **AWS** - AWS S3 based input/output and Ray based EC2 instances
+- **Scale** - Tested on 200 TB of data without downsampling
 
 ---
 
@@ -111,18 +119,31 @@ Questions or want to contribute? Please open an issue..
 
 ## High Level Approach to Registration, Alignment, and Fusion
 
-We first run **interest point detection** to capture feature points in the dataset, focusing on overlapping regions between tiles. These points drive all downstream alignment.
+This process has a lot of knobs and variations, and when used correctly, can work for a broad range of datasets.
+
+**First, figure out what type of alignment you need.**  
+- Are there translations to shift to?  
+- If so, you’ll likely want to start with a rigid alignment and double-check that the required translations do not span more than the overlapping distance.
 
-Next, we perform **alignment** in two-three stages, with regularized models:
+**A very important thing to keep in mind:** interest-point–based alignment will not work well if you don’t find enough high-quality points that can be matched.  
+- Too few, even if they’re very good, will lead to poor alignment.  
+- The same is true if you have lots of low-quality matches.
 
-1. **Rigid matching + solver** – Match interest points with a rigid model and solve for globally consistent rigid transforms between all tiles.
-2. **Affine matching + solver** – Starting from the rigid solution, repeat matching with an affine model to recover more precise tile transforms.
-3. **Split affine matching + solver** – For very large z-stacks, we recommend first running the split dataset component to chunk tiles into smaller Z-bounds, then repeating affine matching and solving in “split affine” mode to refine local alignment. 
+Once you’ve run the rigid step, how does your data look?  
+- Did the required translations shrink to an acceptable level?  
+- If not, try again with new parameters, keeping the questions above in mind.
 
-All resulting transforms are written back into the input XML.
+At this point, the translational part of your alignment should be in good shape. Now ask: **are additional transformations needed?** If so, you likely need an affine alignment next.
 
-Whether you split or not, once the XML contains your final transforms, you are ready for **fusion**. We recommend viewing the aligned XML in FIJI/BDV to visually confirm alignment quality before running fusion.
+Your dataset should be correctly aligned at this point. If not, there are a number of reasons why, and we have listed some common recurrences and will keep this up to date.
 
+There is a special case in some datasets where the z-stack is very large. In this case, you can use the split-dataset utility, which splits each tile into multiple tiles of your choosing. Then you can run split-affine alignment, allowing for more precise transformations without such imposing global rails.
+
+**Common Causes of Poor Alignment**
+- Not enough quality matches (adjust sigma threshold until you do)
+- Data is not consistent looking (we take a global approach to params)
+- Large translations needed (extened search radius)
+- Translations that extend beyond overlapping span (increase overlap)
 
 ---
 
@@ -177,6 +198,19 @@ Rhapso/
 
 ## Installation
 
+### Option 1: Install from PyPI (recommended)
+
+```bash
+# create and activate a virtual environment
+python -m venv .venv && source .venv/bin/activate
+# or: conda create -n rhapso python=3.10 && conda activate rhapso
+
+# install Rhapso from PyPI
+pip install Rhapso
+```
+
+### Option 2: Install from GitHub (developers)
+
  ```sh
 # clone the repo
 git clone https://github.com/AllenNeuralDynamics/Rhapso.git
@@ -268,21 +302,11 @@ with open("Rhapso/pipelines/ray/param/your_param_file.yml", "r") as file:
 Rhapso/pipelines/ray/aws/config/
 ```
 
-### 4. Update config file to point to whl location in setup_commands
-```python
-- aws s3 cp s3://rhapso-whl-v2/Rhapso-0.1.8-py3-none-any.whl /tmp/Rhapso-0.1.8-py3-none-any.whl  
-```
-
 ### 5. Update alignment pipeline script to point to config file
 ```python
 unified_yml = "your_cluster_config_file_name.yml"
 ```
 
-### 6. Create whl file and upload to s3
-```python
-python setup.py sdist bdist_wheel
-```
-
 ### 7. Run AWS alignment pipeline script
 ```python
 python Rhapso/pipelines/ray/aws/alignment_pipeline.py

{rhapso-0.1.95.dist-info → rhapso-0.1.96.dist-info}/RECORD

@@ -90,12 +90,12 @@ Rhapso/split_dataset/save_points.py,sha256=k-jH-slmxkbrxDl-uJvDkwOedi6cg7md3kg_a
 Rhapso/split_dataset/save_xml.py,sha256=Iq1UdFa8sdnWGygfIpDi4F5In-SCWggpl7lnuDTxkHE,14280
 Rhapso/split_dataset/split_images.py,sha256=2RzAi0btV1tmh4le9QotRif1IYUU6_4pLcGGpFBM9zk,22434
 Rhapso/split_dataset/xml_to_dataframe_split.py,sha256=ByaLzJ4sqT417UiCQU31_CS_V4Jms7pjMbBl0ZdSNNA,8570
-rhapso-0.1.95.dist-info/licenses/LICENSE,sha256=U0Y7B3gZJHXpjJVLgTQjM8e_c8w4JJpLgGhIdsoFR1Y,1092
+rhapso-0.1.96.dist-info/licenses/LICENSE,sha256=U0Y7B3gZJHXpjJVLgTQjM8e_c8w4JJpLgGhIdsoFR1Y,1092
 tests/__init__.py,sha256=LYf6ZGyYRcduFFSaOLmnw3rTyfS3XLib0dsTHDWH0jo,37
 tests/test_detection.py,sha256=NtFYR_du9cbKrclQcNiJYsKzyqly6ivF61pw6_NICcM,440
 tests/test_matching.py,sha256=QX0ekSdyIkPpAsXHfSMqJUUlNZg09caSlhhUM63MduM,697
 tests/test_solving.py,sha256=t8I9XPV_4ZFM-DJpgvdYXxkG2_4DQgqs-FFyE5w8Nfg,695
-rhapso-0.1.95.dist-info/METADATA,sha256=UkHXa7SU8DCGNLTKvPdyFM2w-f1rxsbdJbNqczUreC4,16830
-rhapso-0.1.95.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
-rhapso-0.1.95.dist-info/top_level.txt,sha256=NXvsrsTfdowWbM7MxEjkDZE2Jo74lmq7ruWkp70JjSw,13
-rhapso-0.1.95.dist-info/RECORD,,
+rhapso-0.1.96.dist-info/METADATA,sha256=-q4TsuDbH67FN4eXEhxwprGeEFLit211AOXdxnCKYNg,17741
+rhapso-0.1.96.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+rhapso-0.1.96.dist-info/top_level.txt,sha256=NXvsrsTfdowWbM7MxEjkDZE2Jo74lmq7ruWkp70JjSw,13
+rhapso-0.1.96.dist-info/RECORD,,