Merge pull request #62 from oanegros/ome-zarr

version 2.0.0

.github/workflows/tests.yml

@@ -26,6 +26,7 @@ jobs:
           cache: 'pip'
       # - run: pip install bpy==${{ matrix.blender-version }}
 
+
       - name: Install poetry
         run: pip install poetry
       - name: Install
@@ -36,5 +37,23 @@ jobs:
       - name: Install tif_loader
         run: pip install .
 
+    #   - name: Install pyopenvdb
+    #     if: matrix.os == 'ubuntu-latest'
+    #     run:
+    #         conda install openvdb
+    #     # run: |
+        #     cd $(poetry run python -c "import os; import bpy; print(os.path.dirname(bpy.__file__)+'/../../../../../')")
+        #     ORIGIN=`pwd`
+        #     svn export https://svn.blender.org/svnroot/bf-blender/trunk/lib/linux_x86_64_glibc_228/python/lib/python3.10/site-packages/pyopenvdb.so@r63589
+        #     pip install patchelf
+        #     patchelf --set-rpath '$ORIGIN/bpy/lib' pyopenvdb.so
+        #     echo $?
+        #     ls $ORIGIN/bpy/lib
+        #     echo ""
+        #     ls $ORIGIN/bpy
+        #     echo ""
+        #     ls $ORIGIN
+
+
       - name: Run Tests
         run: pytest --verbose 

.gitignore

@@ -159,3 +159,7 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+*.abc
+tests/.DS_Store
+.DS_Store
+.DS_Store

README.md

@@ -4,70 +4,46 @@ This is a project building bioimage support for the open source software blender
 Please make some pretty figures with this add-on! 
 If you post using this addon on social media please either tag me (@GrosOane on twitter) or use hashtag `#microscopynodes`.
 
-You can now also find the add-on on the Blender extensions platform under https://extensions.blender.org/approval-queue/microscopynodes/ (currently still awaiting review by blender).
+You can download and install the add-on on the [Blender extensions platform](https://extensions.blender.org/add-ons/microscopynodes/) or by searching for Microscopy Nodes in the Extensions in your Blender preferences. For installing with earlier Blender versions than 4.2, follow the [legacy install instructions](./docs/outdated.md).
 
-## Video introduction
+The add-on will then show up as a window in the `Scene Properties`.
+
+## Video tutorials
 
 See the [video introductions](https://www.youtube.com/playlist?list=PLAv6_GEMrbKdpje81juHowSCw-gWOJwy5) to the microscopynodes add-on on youtube. There's multiple playlists on the account, and they'll show you how to go from installing to rendering a presentation-ready video for fluorescence and electron microscopy.
 
 <img src="./figures/newprettyside.png" width="600"/>
 
 ## Current Features
-The `microscopynodes` Blender addon is still under active development, but some notable features are already supported:
-
-- up to 5D (up to tzcyx in any axis order) tifs are supported. 
-- Axes order and pixel size will be attempted to be read out automatically
-- Otsu initial volumetric emission material is applied
-- Scale bars are added to the `Geometry Nodes` container of your volumetric data
-
-
-
-
-## Installing `microscopynodes`
-
-You can now find the add-on on the Blender extensions platform under https://extensions.blender.org/approval-queue/microscopynodes/ (currently still awaiting review by blender). You can download this and drag it into the Blender 4.2 window.
-
-For older versions than Blender 4.2:
-
-- Download blender from https://www.blender.org/download/. Check the supported blender version next to the release!
-
-- Download the microscopynodes zip file from the [releases page](https://github.com/oanegros/microscopynodes/releases). 
-
-Start blender.
-
-Install the `microscopynodes` Add-On:
-- In Blender go to `Edit > Preferences`
-- Go to `Add-Ons` tab in `Preferences`
-- Press `Install` and give the `tif_loader.zip` file (as .zip)
-- In the added `microscopynodes` add-on window in `Preferences`: press the tick box to enable, and the arrow to unfold the details
-- in the details press `install tifffile`
-- (if this fails please try restarting blender and seeing if it can then find `tifffile`)
+The `microscopynodes` Blender addon supports:
 
-This should create the `microscopynodes` panel in `Scene Properties`.
+- up to 5D (up to tzcyx in any axis order) tifs and OME-Zarr files can be loaded. 
+- Channel interface to define how to load data
+- Replacing a pyramidal dataset with it's higher resolution version
+- Accurate scale bars
+- Load per-index label masks
+- Lazy loading of giant files (no data is loaded in RAM outside what's rendered)
 
 ## Using `microscopynodes`
-Load in tif-files in the file explorer from the panel in `Scene Properties`. 
 
-Loading with preset environment recently had a small bug, fixed on 7th nov 18:45. So either uncheck this or update your tif_loader(see below), if you have this issue. For any other problems, please open an [issue](https://github.com/oanegros/microscopynodes/issues).
+Load any tif or zarr file by inputting the path or URL in the appropriate window in the `Microscopy Nodes` panel. This will read out metadata and prompt you to define how you want to load the data.
 
-- The `microscopynodes` panel should be able to automatically read out your axis order and pixel size, but these can otherwise also manually be entered
-- Any tif stack from zyx to tzcyx (in any axis order) is supported
-- The `microscopynodes` resaves your tif as a `.vdb` file (in a `blender_volumes` subfolder) and loads this as a volume object in your blender scene, connected to a `Container` object.
-- With large files (over 2048 px in an axis), the volumes will be split to avoid blender crashes.
-- With the `Import option: Force Remake` you will force remaking the vdb files, if this is unchecked and the vdb files exist, these will be loaded.
-- With the `Import option: Preset Environment` some default environment variables will be set. These overwrite current other environment settings, but are useful for quickly looking at data:
-  - Sets background to black (as emission material is default)
-  - Sets `Eevee` volumetric `tile_size` to 2 px (might be heavy for enormous data)
-  - Sets `Cycles` `Samples` to manageable numbers for volumetric data
-  - Sets `View Transform` to `Standard` (the default `Filmic` crunches dynamic range post-render)
+- generic options
+    - axis order
+    - pixel size in µm
+    - dataset (for pyramidal Zarr data)
+    - [reload data](./docs/settings.md#reload)
 
-Upon load, multiple defaults are applied, but all of these can be changed as granularly as you want.
+- per-channel load options:
+    - load [volumetric data](./docs/objects.md#volumes)
+    - load [Blender isosurface](./docs/objects.md#surfaces)
+    - load [labelmask](./docs/objects.md#masks)
 
+- per-channel visuzalization options:
+    - [emission](./docs/settings.md#emission)
+    - [surface resolution](./docs/settings.md#surface-resolution)
 
-## Updating `microscopynodes`
-To update the `microscopynodes` add-on (future versions may have bugfixes, new features) a few steps need to be taken:
-- In Blender go to `Edit > Preferences`
-- Go to `Add-Ons` tab in `Preferences` and find the `microscopynodes` add-on
-- Press `Remove` 
-- Restart Blender
-- Install the new version.
+- extra options
+    - [data storage location](./docs/settings.md#resave-location)
+    - [overwrite existing local files](./docs/settings.md#overwrite)
+    - [preset environment](./docs/settings.md#preset-environment)

build.py

@@ -12,6 +12,8 @@
 whl_path = "./microscopynodes/wheels"
 blender_path ="/Applications/Blender3.app/Contents/MacOS/Blender"
 
+permanent_whls = ["./microscopynodes/wheels/asciitree-0.3.4.dev1-py3-none-any.whl"]
+
 @dataclass
 class Platform:
     pypi_suffix: str
@@ -29,10 +31,29 @@ class Platform:
 
 
 required_packages = [
+    # scikit-image + scipy is really big, but i cannot remove the fast marching cubes algorithm, or the fast find_objects
+    "scikit-image==0.22.0", 
+
+    "dask==2024.8.0",
+
+    # tif loading
     "tifffile==2023.4.12",
-    "scikit-image==0.22.0",
-]
+    "imagecodecs==2024.6.1", # allows LZW compressed tif loading
 
+    # dependencies of zarr:
+    "fasteners==0.19",
+    "numcodecs==0.13.0",
+    "fsspec==2024.6.0",
+    "aiohttp==3.10.3",
+    # asciitree is permanently added
+
+    # development
+    # "ipycytoscape" # for visualizing dask trees
+]
+nodeps_packages = [ 
+    # zarr relies on one package without .whl (asciitree)
+    "zarr==2.17.2"
+]
 
 build_platforms = [
     windows_x64,
@@ -49,7 +70,9 @@ def run_python(args: str):
 
 def remove_whls():
     for whl_file in glob.glob(os.path.join(whl_path, "*.whl")):
-        os.remove(whl_file)
+        if whl_file not in permanent_whls:
+            os.remove(whl_file)
+    # exit()
 
 
 def download_whls(
@@ -65,10 +88,13 @@ def download_whls(
         remove_whls()
 
     for platform in platforms:
+        print(required_packages, nodeps_packages, f"-m pip download {' '.join(required_packages)} --dest ./microscopynodes/wheels --only-binary=:all: --python-version={python_version} --platform={platform.pypi_suffix}")
         run_python(
             f"-m pip download {' '.join(required_packages)} --dest ./microscopynodes/wheels --only-binary=:all: --python-version={python_version} --platform={platform.pypi_suffix}"
         )
-
+        run_python(
+            f"-m pip download {' '.join(nodeps_packages)} --dest ./microscopynodes/wheels --python-version={python_version} --platform={platform.pypi_suffix} --no-deps"
+        )
 
 def update_toml_whls(platforms):
     # Define the path for wheel files
@@ -92,7 +118,8 @@ def update_toml_whls(platforms):
 
     # Remove the unwanted wheel files from the filesystem
     for whl in to_remove:
-        os.remove(whl)
+        if whl not in permanent_whls:
+            os.remove(whl)
 
     # Load the TOML file
     with open(toml_path, "r") as file:

docs/background.md

@@ -0,0 +1,15 @@
+# Replace data in background
+
+Blender can run and render as a background job without a UI. This is very advantageous if you have very large pyramidal stack sizes you want to render your data at, and access to some form of HPC cluster. 
+To replace your data with a different size, you set up all the [Microscopy Nodes settings](./settings.md) to [reload](./settings.md#reload) at the right scale, and run a headless python script that looks like this:
+```
+import bpy
+bpy.ops.microscopynodes.load_background()
+bpy.ops.wm.save_mainfile()
+```
+by running:
+`/path/to/Blender/executable -b /path/to/blendfile.blend -P /path/to/reload_script.py`
+
+This will then load the data according to the Microscopy Nodes settings, and resave the .blend file. 
+
+You can subsequently render headlessly as well, here you can follow the [Blender documentation on this](https://docs.blender.org/manual/en/latest/advanced/command_line/render.html).

docs/faq.md

@@ -0,0 +1,32 @@
+# Frequently Asked Questions
+If yours is not in here, don't be afraid to open an [issue](https://github.com/oanegros/MicroscopyNodes/issues)!
+
+## How are things transformed?
+
+<details>
+  <summary>How is data transformed on load?</summary>
+The data is scaled to 0.02 blender-meter per pixel on an initial load and centered in x and y. If you reload an image with a differently scaled version, it will adapt itself to the initial scale. You can check the size in pixels, blender meters and micrometers in the `Axes` object.
+</details>
+
+<details>
+  <summary>Why does my volume consist of multiple blocks?</summary>
+Currently, Blender cannot handle volumes that are over 2048 pixels in any axis, so Microscopy Nodes chunks this type of data to smaller blocks. This should still be fully equal data (floating-point datasets may suffer from incorrect normalization), channel chunks are offset to avoid Blender rendering bugs.
+</details>
+
+<details>
+  <summary>Why is my data a bigger file than i expected in Blender?</summary>
+The blender VDB files are saved at 32-bit, and can regrettably not be at smaller precision. However, for functionality, and because very little data in microscopy is over 16-bit, only a 16-bit version of the data is loaded into RAM.
+</details>
+
+## I don't see my data?
+
+<details>
+  <summary>I do not see my surfaces?</summary>
+Try adjusting the threshold in the Surface Geometry Nodes modifier, the visibility of the Surfaces object, or the visibility of each channel in the Geometry Nodes modifier.
+</details>
+
+<details>
+  <summary>I do not see my volumes?</summary>
+Try adjusting the threshold in the materials, the visibility of the Volumes object, or the visibility of each channel in the Geometry Nodes modifier. If the emission of the channel was off, make sure there is enough light in the scene to reflect (often done with increasing background intensity).
+</details>
+

docs/file_types.md

@@ -0,0 +1,38 @@
+Microscopy Nodes as an add-on mostly exists to read microscopy data, rewrite this into Blender-loadable file formats, and load this with useful presets. 
+
+---
+
+# Input
+Microscopy Nodes supports .tif and .zarr files/containers. These file types are used in microscopy partially because they have very flexible (or flexibly used) specifications. This means supporting all versions these files can exist in is difficult. 
+
+## TIF files
+Microscopy Nodes loads tif files, and is able to read basic metadata of imagej-tif files. LZW-compressed tif is supported. Further OME-Tif metdata is currently not read, if you really need this, please open an isssue on the github.
+
+## OME-Zarr files
+OME-Zarr is a still-developing pyramidal data format with a lot of features, some of which are harder to support in Blender. Please open an issue if you really want a certain feature.
+Microscopy Nodes supports:
+
+- OME-Zarr >= 0.3
+- channel names from `omero`
+- lazy loading (per channel/timpoint at least)
+- dataset selection
+- coordinate transform Scale
+- `labels` metadata
+
+Microscopy Nodes does not support (currently):
+
+- wells/fields
+- affine/translate coordinate transforms
+- bioformats2raw multiple loading (or others with multiple datasets, one could still select the relevant internal path)
+
+
+----
+
+# Output
+Output files are the files used by Blender to render your data.
+
+## VDB files
+The .vdb is the volume file-format that Blender uses, and is very optimized for raytraced rendering of sparse volumes, as this is often necessary in animation for clouds/fire. The Microscopy Nodes vdb files are chunked per timepoint and channel to allow relatively lazy loading, and are chunked at <2048 pixels per axis as oversized volumes can break Eevee.
+
+## ABC files
+The .abc files are the way label masks are stored, as these files allow changing the entire geometry of each object for each timepoint. These are written through the Blender writing pipeline for each separate object, which is part of why label mask loading can be slow for dense masks.