Rhapso 0.1.94__tar.gz → 0.1.96__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. {rhapso-0.1.94 → rhapso-0.1.96}/PKG-INFO +55 -34
  2. {rhapso-0.1.94 → rhapso-0.1.96}/README.md +53 -29
  3. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso.egg-info/PKG-INFO +55 -34
  4. {rhapso-0.1.94 → rhapso-0.1.96}/setup.py +5 -4
  5. {rhapso-0.1.94 → rhapso-0.1.96}/LICENSE +0 -0
  6. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/__init__.py +0 -0
  7. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/data_prep/__init__.py +0 -0
  8. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/data_prep/n5_reader.py +0 -0
  9. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/data_prep/s3_big_stitcher_reader.py +0 -0
  10. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/data_prep/xml_to_dataframe.py +0 -0
  11. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/detection/__init__.py +0 -0
  12. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/detection/advanced_refinement.py +0 -0
  13. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/detection/difference_of_gaussian.py +0 -0
  14. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/detection/image_reader.py +0 -0
  15. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/detection/metadata_builder.py +0 -0
  16. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/detection/overlap_detection.py +0 -0
  17. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/detection/points_validation.py +0 -0
  18. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/detection/save_interest_points.py +0 -0
  19. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/detection/view_transform_models.py +0 -0
  20. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/__init__.py +0 -0
  21. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/affine_fusion/__init__.py +0 -0
  22. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/affine_fusion/blend.py +0 -0
  23. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/affine_fusion/fusion.py +0 -0
  24. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/affine_fusion/geometry.py +0 -0
  25. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/affine_fusion/io.py +0 -0
  26. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/affine_fusion/script_utils.py +0 -0
  27. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/affine_fusion/setup.py +0 -0
  28. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/affine_fusion_worker.py +0 -0
  29. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/__init__.py +0 -0
  30. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_hcr_data_transformation/__init__.py +0 -0
  31. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_hcr_data_transformation/compress/__init__.py +0 -0
  32. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_hcr_data_transformation/compress/czi_to_zarr.py +0 -0
  33. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_hcr_data_transformation/compress/zarr_writer.py +0 -0
  34. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_hcr_data_transformation/models.py +0 -0
  35. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_hcr_data_transformation/utils/__init__.py +0 -0
  36. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_hcr_data_transformation/utils/utils.py +0 -0
  37. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_hcr_data_transformation/zeiss_job.py +0 -0
  38. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_z1_radial_correction/__init__.py +0 -0
  39. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_z1_radial_correction/array_to_zarr.py +0 -0
  40. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_z1_radial_correction/radial_correction.py +0 -0
  41. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_z1_radial_correction/run_capsule.py +0 -0
  42. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_z1_radial_correction/utils/__init__.py +0 -0
  43. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_z1_radial_correction/utils/utils.py +0 -0
  44. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale/aind_z1_radial_correction/worker.py +0 -0
  45. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/multiscale_worker.py +0 -0
  46. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/__init__.py +0 -0
  47. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/dispim_link.py +0 -0
  48. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/exaspim_link.py +0 -0
  49. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/hcr_link.py +0 -0
  50. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/iSPIM_top.py +0 -0
  51. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/link_utils.py +0 -0
  52. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/main.py +0 -0
  53. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/ng_layer.py +0 -0
  54. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/ng_state.py +0 -0
  55. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/parsers.py +0 -0
  56. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/raw_link.py +0 -0
  57. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/utils/__init__.py +0 -0
  58. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/utils/shader_utils.py +0 -0
  59. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/utils/transfer.py +0 -0
  60. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen/utils/utils.py +0 -0
  61. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/fusion/neuroglancer_link_gen_worker.py +0 -0
  62. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/matching/__init__.py +0 -0
  63. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/matching/load_and_transform_points.py +0 -0
  64. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/matching/ransac_matching.py +0 -0
  65. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/matching/save_matches.py +0 -0
  66. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/matching/xml_parser.py +0 -0
  67. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/__init__.py +0 -0
  68. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/__init__.py +0 -0
  69. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/aws/__init__.py +0 -0
  70. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/aws/alignment_pipeline.py +0 -0
  71. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/aws/config/__init__.py +0 -0
  72. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/evaluation.py +0 -0
  73. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/interest_point_detection.py +0 -0
  74. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/interest_point_matching.py +0 -0
  75. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/local/__init__.py +0 -0
  76. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/local/alignment_pipeline.py +0 -0
  77. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/matching_stats.py +0 -0
  78. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/param/__init__.py +0 -0
  79. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/solver.py +0 -0
  80. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/pipelines/ray/split_dataset.py +0 -0
  81. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/__init__.py +0 -0
  82. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/compute_tiles.py +0 -0
  83. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/concatenate_models.py +0 -0
  84. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/connected_graphs.py +0 -0
  85. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/data_prep.py +0 -0
  86. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/global_optimization.py +0 -0
  87. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/model_and_tile_setup.py +0 -0
  88. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/pre_align_tiles.py +0 -0
  89. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/save_results.py +0 -0
  90. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/view_transforms.py +0 -0
  91. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/solver/xml_to_dataframe_solver.py +0 -0
  92. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/split_dataset/__init__.py +0 -0
  93. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/split_dataset/compute_grid_rules.py +0 -0
  94. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/split_dataset/save_points.py +0 -0
  95. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/split_dataset/save_xml.py +0 -0
  96. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/split_dataset/split_images.py +0 -0
  97. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso/split_dataset/xml_to_dataframe_split.py +0 -0
  98. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso.egg-info/SOURCES.txt +0 -0
  99. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso.egg-info/dependency_links.txt +0 -0
  100. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso.egg-info/requires.txt +0 -0
  101. {rhapso-0.1.94 → rhapso-0.1.96}/Rhapso.egg-info/top_level.txt +0 -0
  102. {rhapso-0.1.94 → rhapso-0.1.96}/pyproject.toml +0 -0
  103. {rhapso-0.1.94 → rhapso-0.1.96}/setup.cfg +0 -0
  104. {rhapso-0.1.94 → rhapso-0.1.96}/tests/__init__.py +0 -0
  105. {rhapso-0.1.94 → rhapso-0.1.96}/tests/test_detection.py +0 -0
  106. {rhapso-0.1.94 → rhapso-0.1.96}/tests/test_matching.py +0 -0
  107. {rhapso-0.1.94 → rhapso-0.1.96}/tests/test_solving.py +0 -0
@@ -1,13 +1,11 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: Rhapso
3
- Version: 0.1.94
3
+ Version: 0.1.96
4
4
  Summary: A python package for aligning and stitching light sheet fluorescence microscopy images together
5
- Home-page: https://github.com/AllenNeuralDynamics/Rhapso
6
5
  Author: ND
7
6
  Author-email: sean.fite@alleninstitute.org
8
7
  Project-URL: Source, https://github.com/AllenNeuralDynamics/Rhapso
9
- Project-URL: Bug Tracker, https://github.com/AllenNeuralDynamics/Rhapso/issues
10
- Project-URL: Changelog, https://github.com/AllenNeuralDynamics/Rhapso/releases
8
+ Project-URL: Roadmap, https://github.com/AllenNeuralDynamics/Rhapso/issues
11
9
  Classifier: Development Status :: 3 - Alpha
12
10
  Classifier: Intended Audience :: Developers
13
11
  Classifier: Natural Language :: English
@@ -40,7 +38,6 @@ Dynamic: author-email
40
38
  Dynamic: classifier
41
39
  Dynamic: description
42
40
  Dynamic: description-content-type
43
- Dynamic: home-page
44
41
  Dynamic: license-file
45
42
  Dynamic: project-url
46
43
  Dynamic: requires-dist
@@ -49,10 +46,10 @@ Dynamic: summary
49
46
 
50
47
  # Rhapso
51
48
 
52
- **Rhapso** is a modular Python toolkit for interest point based registration, alignment, and fusing of large-scale microscopy datasets.
49
+ This is the code base for **Rhapso**, a modular Python toolkit for the alignment and stitching of large-scale microscopy datasets.
53
50
 
54
51
  [![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
55
- [![Python Version](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3110/)
52
+ [![Python Version](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3100/)
56
53
  [![Documentation](https://img.shields.io/badge/docs-wiki-blue)](https://github.com/AllenNeuralDynamics/Rhapso/wiki)
57
54
 
58
55
  <!-- ## Example Usage Media Content Coming Soon....
@@ -63,7 +60,7 @@ Dynamic: summary
63
60
  ## Table of Contents
64
61
  - [Summary](#summary)
65
62
  - [Contact](#contact)
66
- - [Features](#features)
63
+ - [Supported Features](#supported-features)
67
64
  - [Performance](#performance)
68
65
  - [Layout](#layout)
69
66
  - [Installation](#installation)
@@ -80,7 +77,7 @@ Dynamic: summary
80
77
 
81
78
  <br>
82
79
 
83
- **Update 11/26/25**
80
+ **Update 1/12/26**
84
81
  --------
85
82
  Rhapso is still loading... and while we wrap up development, a couple things to know if you are outside the Allen Institute:
86
83
  - This process requires a very specific XML structure to work.
@@ -89,11 +86,15 @@ Rhapso is still loading... and while we wrap up development, a couple things to
89
86
  <br>
90
87
 
91
88
  ## Summary
92
- Rhapso is a set of Python components for registration, alignment, and stitching of large-scale, 3D, overlapping tile-based, multiscale microscopy datasets.
89
+ 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.
93
90
 
94
- 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.
91
+ Rhapso is published on PyPI and can be installed with:
95
92
 
96
- Current data loaders support Zarr and Tiff.
93
+ ```bash
94
+ pip install Rhapso
95
+ ```
96
+
97
+ Rhapso was developed by the Allen Institute for Neural Dynamics.
97
98
 
98
99
  <br>
99
100
 
@@ -102,11 +103,15 @@ Questions or want to contribute? Please open an issue..
102
103
 
103
104
  <br>
104
105
 
105
- ## Features
106
- - **Interest Point Detection** - using DOG based feature detection
107
- - **Interest Point Matching** - using descriptor based RANSAC to match feature points
108
- - **Global Optimization** - aligning matched features per tile, globally
109
- - **Validation and Visualization Tools** - validate component specific results for the best output
106
+ ## Supported Features
107
+ - **Interest Point Detection** - DOG based feature detection
108
+ - **Interest Point Matching** - Descriptor based RANSAC to match feature points
109
+ - **Global Optimization** - Align matched features between tile pairs globally
110
+ - **Validation and Visualization Tools** - Validate component specific results for the best output
111
+ - **ZARR** - Zarr data as input
112
+ - **TIFF** - Tiff data as input
113
+ - **AWS** - AWS S3 based input/output and Ray based EC2 instances
114
+ - **Scale** - Tested on 200 TB of data without downsampling
110
115
 
111
116
  ---
112
117
 
@@ -114,18 +119,31 @@ Questions or want to contribute? Please open an issue..
114
119
 
115
120
  ## High Level Approach to Registration, Alignment, and Fusion
116
121
 
117
- 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.
122
+ This process has a lot of knobs and variations, and when used correctly, can work for a broad range of datasets.
123
+
124
+ **First, figure out what type of alignment you need.**
125
+ - Are there translations to shift to?
126
+ - 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.
118
127
 
119
- Next, we perform **alignment** in two-three stages, with regularized models:
128
+ **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.
129
+ - Too few, even if they’re very good, will lead to poor alignment.
130
+ - The same is true if you have lots of low-quality matches.
120
131
 
121
- 1. **Rigid matching + solver** – Match interest points with a rigid model and solve for globally consistent rigid transforms between all tiles.
122
- 2. **Affine matching + solver** – Starting from the rigid solution, repeat matching with an affine model to recover more precise tile transforms.
123
- 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.
132
+ Once you’ve run the rigid step, how does your data look?
133
+ - Did the required translations shrink to an acceptable level?
134
+ - If not, try again with new parameters, keeping the questions above in mind.
124
135
 
125
- All resulting transforms are written back into the input XML.
136
+ 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.
126
137
 
127
- 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.
138
+ 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.
128
139
 
140
+ 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.
141
+
142
+ **Common Causes of Poor Alignment**
143
+ - Not enough quality matches (adjust sigma threshold until you do)
144
+ - Data is not consistent looking (we take a global approach to params)
145
+ - Large translations needed (extened search radius)
146
+ - Translations that extend beyond overlapping span (increase overlap)
129
147
 
130
148
  ---
131
149
 
@@ -180,6 +198,19 @@ Rhapso/
180
198
 
181
199
  ## Installation
182
200
 
201
+ ### Option 1: Install from PyPI (recommended)
202
+
203
+ ```bash
204
+ # create and activate a virtual environment
205
+ python -m venv .venv && source .venv/bin/activate
206
+ # or: conda create -n rhapso python=3.10 && conda activate rhapso
207
+
208
+ # install Rhapso from PyPI
209
+ pip install Rhapso
210
+ ```
211
+
212
+ ### Option 2: Install from GitHub (developers)
213
+
183
214
  ```sh
184
215
  # clone the repo
185
216
  git clone https://github.com/AllenNeuralDynamics/Rhapso.git
@@ -271,21 +302,11 @@ with open("Rhapso/pipelines/ray/param/your_param_file.yml", "r") as file:
271
302
  Rhapso/pipelines/ray/aws/config/
272
303
  ```
273
304
 
274
- ### 4. Update config file to point to whl location in setup_commands
275
- ```python
276
- - aws s3 cp s3://rhapso-whl-v2/Rhapso-0.1.8-py3-none-any.whl /tmp/Rhapso-0.1.8-py3-none-any.whl
277
- ```
278
-
279
305
  ### 5. Update alignment pipeline script to point to config file
280
306
  ```python
281
307
  unified_yml = "your_cluster_config_file_name.yml"
282
308
  ```
283
309
 
284
- ### 6. Create whl file and upload to s3
285
- ```python
286
- python setup.py sdist bdist_wheel
287
- ```
288
-
289
310
  ### 7. Run AWS alignment pipeline script
290
311
  ```python
291
312
  python Rhapso/pipelines/ray/aws/alignment_pipeline.py
@@ -1,9 +1,9 @@
1
1
  # Rhapso
2
2
 
3
- **Rhapso** is a modular Python toolkit for interest point based registration, alignment, and fusing of large-scale microscopy datasets.
3
+ This is the code base for **Rhapso**, a modular Python toolkit for the alignment and stitching of large-scale microscopy datasets.
4
4
 
5
5
  [![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
6
- [![Python Version](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3110/)
6
+ [![Python Version](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3100/)
7
7
  [![Documentation](https://img.shields.io/badge/docs-wiki-blue)](https://github.com/AllenNeuralDynamics/Rhapso/wiki)
8
8
 
9
9
  <!-- ## Example Usage Media Content Coming Soon....
@@ -14,7 +14,7 @@
14
14
  ## Table of Contents
15
15
  - [Summary](#summary)
16
16
  - [Contact](#contact)
17
- - [Features](#features)
17
+ - [Supported Features](#supported-features)
18
18
  - [Performance](#performance)
19
19
  - [Layout](#layout)
20
20
  - [Installation](#installation)
@@ -31,7 +31,7 @@
31
31
 
32
32
  <br>
33
33
 
34
- **Update 11/26/25**
34
+ **Update 1/12/26**
35
35
  --------
36
36
  Rhapso is still loading... and while we wrap up development, a couple things to know if you are outside the Allen Institute:
37
37
  - This process requires a very specific XML structure to work.
@@ -40,11 +40,15 @@ Rhapso is still loading... and while we wrap up development, a couple things to
40
40
  <br>
41
41
 
42
42
  ## Summary
43
- Rhapso is a set of Python components for registration, alignment, and stitching of large-scale, 3D, overlapping tile-based, multiscale microscopy datasets.
43
+ 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.
44
44
 
45
- 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.
45
+ Rhapso is published on PyPI and can be installed with:
46
46
 
47
- Current data loaders support Zarr and Tiff.
47
+ ```bash
48
+ pip install Rhapso
49
+ ```
50
+
51
+ Rhapso was developed by the Allen Institute for Neural Dynamics.
48
52
 
49
53
  <br>
50
54
 
@@ -53,11 +57,15 @@ Questions or want to contribute? Please open an issue..
53
57
 
54
58
  <br>
55
59
 
56
- ## Features
57
- - **Interest Point Detection** - using DOG based feature detection
58
- - **Interest Point Matching** - using descriptor based RANSAC to match feature points
59
- - **Global Optimization** - aligning matched features per tile, globally
60
- - **Validation and Visualization Tools** - validate component specific results for the best output
60
+ ## Supported Features
61
+ - **Interest Point Detection** - DOG based feature detection
62
+ - **Interest Point Matching** - Descriptor based RANSAC to match feature points
63
+ - **Global Optimization** - Align matched features between tile pairs globally
64
+ - **Validation and Visualization Tools** - Validate component specific results for the best output
65
+ - **ZARR** - Zarr data as input
66
+ - **TIFF** - Tiff data as input
67
+ - **AWS** - AWS S3 based input/output and Ray based EC2 instances
68
+ - **Scale** - Tested on 200 TB of data without downsampling
61
69
 
62
70
  ---
63
71
 
@@ -65,18 +73,31 @@ Questions or want to contribute? Please open an issue..
65
73
 
66
74
  ## High Level Approach to Registration, Alignment, and Fusion
67
75
 
68
- 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.
76
+ This process has a lot of knobs and variations, and when used correctly, can work for a broad range of datasets.
77
+
78
+ **First, figure out what type of alignment you need.**
79
+ - Are there translations to shift to?
80
+ - 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.
69
81
 
70
- Next, we perform **alignment** in two-three stages, with regularized models:
82
+ **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.
83
+ - Too few, even if they’re very good, will lead to poor alignment.
84
+ - The same is true if you have lots of low-quality matches.
71
85
 
72
- 1. **Rigid matching + solver** – Match interest points with a rigid model and solve for globally consistent rigid transforms between all tiles.
73
- 2. **Affine matching + solver** – Starting from the rigid solution, repeat matching with an affine model to recover more precise tile transforms.
74
- 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.
86
+ Once you’ve run the rigid step, how does your data look?
87
+ - Did the required translations shrink to an acceptable level?
88
+ - If not, try again with new parameters, keeping the questions above in mind.
75
89
 
76
- All resulting transforms are written back into the input XML.
90
+ 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.
77
91
 
78
- 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.
92
+ 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.
79
93
 
94
+ 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.
95
+
96
+ **Common Causes of Poor Alignment**
97
+ - Not enough quality matches (adjust sigma threshold until you do)
98
+ - Data is not consistent looking (we take a global approach to params)
99
+ - Large translations needed (extened search radius)
100
+ - Translations that extend beyond overlapping span (increase overlap)
80
101
 
81
102
  ---
82
103
 
@@ -131,6 +152,19 @@ Rhapso/
131
152
 
132
153
  ## Installation
133
154
 
155
+ ### Option 1: Install from PyPI (recommended)
156
+
157
+ ```bash
158
+ # create and activate a virtual environment
159
+ python -m venv .venv && source .venv/bin/activate
160
+ # or: conda create -n rhapso python=3.10 && conda activate rhapso
161
+
162
+ # install Rhapso from PyPI
163
+ pip install Rhapso
164
+ ```
165
+
166
+ ### Option 2: Install from GitHub (developers)
167
+
134
168
  ```sh
135
169
  # clone the repo
136
170
  git clone https://github.com/AllenNeuralDynamics/Rhapso.git
@@ -222,21 +256,11 @@ with open("Rhapso/pipelines/ray/param/your_param_file.yml", "r") as file:
222
256
  Rhapso/pipelines/ray/aws/config/
223
257
  ```
224
258
 
225
- ### 4. Update config file to point to whl location in setup_commands
226
- ```python
227
- - aws s3 cp s3://rhapso-whl-v2/Rhapso-0.1.8-py3-none-any.whl /tmp/Rhapso-0.1.8-py3-none-any.whl
228
- ```
229
-
230
259
  ### 5. Update alignment pipeline script to point to config file
231
260
  ```python
232
261
  unified_yml = "your_cluster_config_file_name.yml"
233
262
  ```
234
263
 
235
- ### 6. Create whl file and upload to s3
236
- ```python
237
- python setup.py sdist bdist_wheel
238
- ```
239
-
240
264
  ### 7. Run AWS alignment pipeline script
241
265
  ```python
242
266
  python Rhapso/pipelines/ray/aws/alignment_pipeline.py
@@ -1,13 +1,11 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: Rhapso
3
- Version: 0.1.94
3
+ Version: 0.1.96
4
4
  Summary: A python package for aligning and stitching light sheet fluorescence microscopy images together
5
- Home-page: https://github.com/AllenNeuralDynamics/Rhapso
6
5
  Author: ND
7
6
  Author-email: sean.fite@alleninstitute.org
8
7
  Project-URL: Source, https://github.com/AllenNeuralDynamics/Rhapso
9
- Project-URL: Bug Tracker, https://github.com/AllenNeuralDynamics/Rhapso/issues
10
- Project-URL: Changelog, https://github.com/AllenNeuralDynamics/Rhapso/releases
8
+ Project-URL: Roadmap, https://github.com/AllenNeuralDynamics/Rhapso/issues
11
9
  Classifier: Development Status :: 3 - Alpha
12
10
  Classifier: Intended Audience :: Developers
13
11
  Classifier: Natural Language :: English
@@ -40,7 +38,6 @@ Dynamic: author-email
40
38
  Dynamic: classifier
41
39
  Dynamic: description
42
40
  Dynamic: description-content-type
43
- Dynamic: home-page
44
41
  Dynamic: license-file
45
42
  Dynamic: project-url
46
43
  Dynamic: requires-dist
@@ -49,10 +46,10 @@ Dynamic: summary
49
46
 
50
47
  # Rhapso
51
48
 
52
- **Rhapso** is a modular Python toolkit for interest point based registration, alignment, and fusing of large-scale microscopy datasets.
49
+ This is the code base for **Rhapso**, a modular Python toolkit for the alignment and stitching of large-scale microscopy datasets.
53
50
 
54
51
  [![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
55
- [![Python Version](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3110/)
52
+ [![Python Version](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3100/)
56
53
  [![Documentation](https://img.shields.io/badge/docs-wiki-blue)](https://github.com/AllenNeuralDynamics/Rhapso/wiki)
57
54
 
58
55
  <!-- ## Example Usage Media Content Coming Soon....
@@ -63,7 +60,7 @@ Dynamic: summary
63
60
  ## Table of Contents
64
61
  - [Summary](#summary)
65
62
  - [Contact](#contact)
66
- - [Features](#features)
63
+ - [Supported Features](#supported-features)
67
64
  - [Performance](#performance)
68
65
  - [Layout](#layout)
69
66
  - [Installation](#installation)
@@ -80,7 +77,7 @@ Dynamic: summary
80
77
 
81
78
  <br>
82
79
 
83
- **Update 11/26/25**
80
+ **Update 1/12/26**
84
81
  --------
85
82
  Rhapso is still loading... and while we wrap up development, a couple things to know if you are outside the Allen Institute:
86
83
  - This process requires a very specific XML structure to work.
@@ -89,11 +86,15 @@ Rhapso is still loading... and while we wrap up development, a couple things to
89
86
  <br>
90
87
 
91
88
  ## Summary
92
- Rhapso is a set of Python components for registration, alignment, and stitching of large-scale, 3D, overlapping tile-based, multiscale microscopy datasets.
89
+ 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.
93
90
 
94
- 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.
91
+ Rhapso is published on PyPI and can be installed with:
95
92
 
96
- Current data loaders support Zarr and Tiff.
93
+ ```bash
94
+ pip install Rhapso
95
+ ```
96
+
97
+ Rhapso was developed by the Allen Institute for Neural Dynamics.
97
98
 
98
99
  <br>
99
100
 
@@ -102,11 +103,15 @@ Questions or want to contribute? Please open an issue..
102
103
 
103
104
  <br>
104
105
 
105
- ## Features
106
- - **Interest Point Detection** - using DOG based feature detection
107
- - **Interest Point Matching** - using descriptor based RANSAC to match feature points
108
- - **Global Optimization** - aligning matched features per tile, globally
109
- - **Validation and Visualization Tools** - validate component specific results for the best output
106
+ ## Supported Features
107
+ - **Interest Point Detection** - DOG based feature detection
108
+ - **Interest Point Matching** - Descriptor based RANSAC to match feature points
109
+ - **Global Optimization** - Align matched features between tile pairs globally
110
+ - **Validation and Visualization Tools** - Validate component specific results for the best output
111
+ - **ZARR** - Zarr data as input
112
+ - **TIFF** - Tiff data as input
113
+ - **AWS** - AWS S3 based input/output and Ray based EC2 instances
114
+ - **Scale** - Tested on 200 TB of data without downsampling
110
115
 
111
116
  ---
112
117
 
@@ -114,18 +119,31 @@ Questions or want to contribute? Please open an issue..
114
119
 
115
120
  ## High Level Approach to Registration, Alignment, and Fusion
116
121
 
117
- 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.
122
+ This process has a lot of knobs and variations, and when used correctly, can work for a broad range of datasets.
123
+
124
+ **First, figure out what type of alignment you need.**
125
+ - Are there translations to shift to?
126
+ - 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.
118
127
 
119
- Next, we perform **alignment** in two-three stages, with regularized models:
128
+ **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.
129
+ - Too few, even if they’re very good, will lead to poor alignment.
130
+ - The same is true if you have lots of low-quality matches.
120
131
 
121
- 1. **Rigid matching + solver** – Match interest points with a rigid model and solve for globally consistent rigid transforms between all tiles.
122
- 2. **Affine matching + solver** – Starting from the rigid solution, repeat matching with an affine model to recover more precise tile transforms.
123
- 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.
132
+ Once you’ve run the rigid step, how does your data look?
133
+ - Did the required translations shrink to an acceptable level?
134
+ - If not, try again with new parameters, keeping the questions above in mind.
124
135
 
125
- All resulting transforms are written back into the input XML.
136
+ 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.
126
137
 
127
- 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.
138
+ 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.
128
139
 
140
+ 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.
141
+
142
+ **Common Causes of Poor Alignment**
143
+ - Not enough quality matches (adjust sigma threshold until you do)
144
+ - Data is not consistent looking (we take a global approach to params)
145
+ - Large translations needed (extened search radius)
146
+ - Translations that extend beyond overlapping span (increase overlap)
129
147
 
130
148
  ---
131
149
 
@@ -180,6 +198,19 @@ Rhapso/
180
198
 
181
199
  ## Installation
182
200
 
201
+ ### Option 1: Install from PyPI (recommended)
202
+
203
+ ```bash
204
+ # create and activate a virtual environment
205
+ python -m venv .venv && source .venv/bin/activate
206
+ # or: conda create -n rhapso python=3.10 && conda activate rhapso
207
+
208
+ # install Rhapso from PyPI
209
+ pip install Rhapso
210
+ ```
211
+
212
+ ### Option 2: Install from GitHub (developers)
213
+
183
214
  ```sh
184
215
  # clone the repo
185
216
  git clone https://github.com/AllenNeuralDynamics/Rhapso.git
@@ -271,21 +302,11 @@ with open("Rhapso/pipelines/ray/param/your_param_file.yml", "r") as file:
271
302
  Rhapso/pipelines/ray/aws/config/
272
303
  ```
273
304
 
274
- ### 4. Update config file to point to whl location in setup_commands
275
- ```python
276
- - aws s3 cp s3://rhapso-whl-v2/Rhapso-0.1.8-py3-none-any.whl /tmp/Rhapso-0.1.8-py3-none-any.whl
277
- ```
278
-
279
305
  ### 5. Update alignment pipeline script to point to config file
280
306
  ```python
281
307
  unified_yml = "your_cluster_config_file_name.yml"
282
308
  ```
283
309
 
284
- ### 6. Create whl file and upload to s3
285
- ```python
286
- python setup.py sdist bdist_wheel
287
- ```
288
-
289
310
  ### 7. Run AWS alignment pipeline script
290
311
  ```python
291
312
  python Rhapso/pipelines/ray/aws/alignment_pipeline.py
@@ -7,17 +7,15 @@ long_description = (this_directory / "README.md").read_text(encoding="utf-8")
7
7
 
8
8
  setup(
9
9
  name='Rhapso',
10
- version='0.1.94',
10
+ version='0.1.96',
11
11
  author='ND',
12
12
  author_email='sean.fite@alleninstitute.org',
13
13
  description='A python package for aligning and stitching light sheet fluorescence microscopy images together',
14
14
  long_description=long_description,
15
15
  long_description_content_type='text/markdown',
16
- url='https://github.com/AllenNeuralDynamics/Rhapso',
17
16
  project_urls={
18
17
  'Source': 'https://github.com/AllenNeuralDynamics/Rhapso',
19
- 'Bug Tracker': 'https://github.com/AllenNeuralDynamics/Rhapso/issues',
20
- 'Changelog': 'https://github.com/AllenNeuralDynamics/Rhapso/releases',
18
+ 'Roadmap': 'https://github.com/AllenNeuralDynamics/Rhapso/issues',
21
19
  },
22
20
  packages=find_packages(),
23
21
  install_requires=[
@@ -51,3 +49,6 @@ setup(
51
49
  ],
52
50
  )
53
51
 
52
+
53
+
54
+
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes