### Initialize pyimagej from a local installation

Source: https://github.com/imagej/pyimagej/blob/main/doc/Initialization.md

Wrap an ImageJ2 gateway around a local ImageJ2 installation, such as Fiji. Replace the example path with your installation's path.

```python
import imagej
ij = imagej.init('/Applications/Fiji.app')
```

--------------------------------

### Initialize ImageJ Gateway (Local Installation)

Source: https://github.com/imagej/pyimagej/blob/main/doc/01-Starting-PyImageJ.ipynb

Initialize the ImageJ gateway from a local installation of Fiji.app. Reproducibility depends on the local installation.

```python
ij = imagej.init('/Applications/Fiji.app')
```

--------------------------------

### Setup Progress Widget

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/pyimagej-ai-guide.ipynb

Initializes and displays a progress bar and status label for tracking the setup process. This widget provides visual feedback during notebook execution.

```python
from IPython.display import display
import ipywidgets as widgets

# Create a progress widget
progress = widgets.IntProgress(
    value=0,
    min=0,
    max=100,
    description='Progress:',
    bar_style='info',
    orientation='horizontal',
    layout=widgets.Layout(width='60%', margin='0 10px 0 0')

)
status_label = widgets.Label(value='Initializing...', layout=widgets.Layout(width='40%'))
display(widgets.HBox(
    [status_label, progress],
    layout=widgets.Layout(align_items='center')
))
```

--------------------------------

### Initialize with Local ImageJ Installation

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/environments/env_interactive.md

Initialize pyimagej using a local installation of ImageJ or Fiji. Provide the absolute path to the application directory.

```python
ij = imagej.init('/path/to/Fiji.app')
```

--------------------------------

### Install and Initialize PyImageJ

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/custom-pyimagej-ai-guide.ipynb

Installs PyImageJ using pip if it's not already imported. It then initializes the PyImageJ instance, specifying the UI mode (interactive or headless) and the Fiji bundle path.

```python
# Install PyImageJ if not already installed
try:
    import imagej
    print("PyImageJ already installed")
except ImportError:
    print("Installing PyImageJ...")
    %pip install pyimagej
    import imagej

# This line avoids linting warnings about being unbounded vars
ij: Any = ij if 'ij' in globals() or 'ij' in locals() else None
ui_mode: Any = ui_mode if 'ui_mode' in globals() or 'ui_mode' in locals() else None

# Initialize PyImageJ (no further downloads needed!)
try:
    # Check if ImageJ is already initialized
    ij.getVersion()
    print(f"PyImageJ already initialized with ImageJ {ij.getVersion()}")
except AttributeError:
    # ij variable is None, safe to initialize
    print(f"Initializing PyImageJ in {ui_mode} mode...")
    ij = imagej.init('./Fiji', mode=ui_mode)
    print(f"PyImageJ initialized with ImageJ {ij.getVersion()}")
except Exception as e:
    # ij exists but might be in bad state, reinitialize
    print(f"Reinitializing PyImageJ (previous state: {e})")
    ij = imagej.init('./Fiji', mode=ui_mode)
    print(f"PyImageJ initialized with ImageJ {ij.getVersion()}")

if ij is not None:
    print("✅ PyImageJ is ready to use! The 'ij' variable contains your ImageJ instance.")
    print(f"UI Mode: {ui_mode}")
    if ui_mode == 'interactive':
        print("💡 Interactive mode enables RoiManager and other GUI features")
    else:
        print("💡 Headless mode - use ij.py.show() for image display")
```

--------------------------------

### Troubleshoot PyImageJ Setup

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/custom-pyimagej-ai-guide.ipynb

Provides a mechanism to view hidden output from specific PyImageJ setup steps, such as downloading PyImageJ or setting up the Fiji bundle, to aid in debugging.

```python
#@title 🛠️ Troubleshooting { display-mode: "form", run: "auto" }
#@markdown We hide as much output as we can to keep this notebook tidy.
#@markdown
#@markdown You can run this cell if you need to see any hidden output from a failing step.

failing_step = "Select problematic step" #@param ["Select problematic step", "Download PyImageJ", "Set up Fiji Bundle"]

try:
    if failing_step == "Download PyImageJ":
        print("--- Download PyImageJ Output ---")
        print(clone_output.show())
    elif failing_step == "Set up Fiji Bundle":
        print("--- Set up Fiji Bundle Output ---")
        print(bundle_setup.show())
except Exception as e:
    print("No captured output for this stage.", e)
```

--------------------------------

### Troubleshoot PyImageJ Setup Steps

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/pyimagej-ai-guide.ipynb

Use this cell to view hidden output from failing setup steps like downloading PyImageJ or setting up the Fiji bundle. Select the problematic step from the dropdown.

```python
#@title 🛠️ Troubleshooting { display-mode: "form", run: "auto" }
#@markdown Use this cell if you need to see any hidden output from a failing configuration step.

status_label.value = 'Setting up troubleshooter...'

failing_step = "Select problematic step" #@param ["Select problematic step", "Download PyImageJ", "Set up Fiji Bundle"]
try:
    if failing_step == "Download PyImageJ":
        print("--- Download PyImageJ Output ---")
        print(clone_output.show())
    elif failing_step == "Set up Fiji Bundle":
        print("--- Set up Fiji Bundle Output ---")
        print(bundle_setup.show())
except Exception as e:
    print("No captured output for this stage.", e)

progress.value += 1
```

--------------------------------

### Setup Fiji Colab Bundle

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/pyimagej-ai-guide.ipynb

Installs Fiji and its dependencies in a Colab environment. It handles downloading, extracting, and merging caches, with retry logic for downloads. Use this when Fiji is not already present.

```python
if not os.path.exists("Fiji"):
    print("Setting up Fiji Colab bundle...")

    # Work in a safe bundle directory to avoid conflicts with existing caches
    bundle_dir = "fiji_colab_bundle"
    original_dir = os.getcwd()

    # Create and enter bundle directory
    os.makedirs(bundle_dir, exist_ok=True)
    os.chdir(bundle_dir)

    # Download bundle
    file_name = "{bundle_name}.tar.gz".format(bundle_name=bundle_name)
    url = "https://github.com/fiji/fiji-builds/releases/download/{bundle_name}/{bundle_name}.tar.gz".format(bundle_name=bundle_name)
    print("Downloading Fiji Colab bundle from {url} ...".format(url=url))
    
    # Keep trying until the file is complete
    max_retries = 3
    retry_count = 0
    while retry_count < max_retries:
        proc = subprocess.Popen(
            ["wget", "--progress=bar:force", "-c", url, "-O", file_name],
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            universal_newlines=True,
            bufsize=1
        )
        
        # Monitor wget progress in real-time
        status_label.value = 'Downloading Fiji bundle (~300MB)...'
        for line in proc.stderr:
            # wget outputs progress to stderr like: "12% [=====>     ] 1,234,567   123KB/s"
            match = re.search(r'(\d+)%', line)
            if match:
                wget_percent = int(match.group(1))
                # Map wget 0-100% to notebook 20-70%
                progress.value = 10 + int(wget_percent * 0.4)
                status_label.value = f'Downloading Fiji bundle...'
        
        proc.wait()
        
        if proc.returncode == 0:
            print("Download finished successfully.")
            break
        elif proc.returncode == 8:  # wget returns 8 for 404/server errors
            stderr_output = proc.stderr if isinstance(proc.stderr, str) else "Unknown error"
            print(f"❌ Download failed: {stderr_output}")
            raise FileNotFoundError(
                f"Bundle not found at {url}. "
                f"Please check that bundle_id '{bundle_id}' exists at "
                f"https://github.com/fiji/fiji-builds/releases"
            )
        else:
            retry_count += 1
            if retry_count < max_retries:
                print("Download interrupted (return code: {}). Retrying in 10 seconds... ({{}}/{})".format(
                    proc.returncode, retry_count, max_retries))
                status_label.value = f'Retrying download ({{}}/{max_retries})...'
                time.sleep(10)
            else:
                print(f"❌ Download failed after {max_retries} attempts")
                raise RuntimeError(f"Failed to download bundle after {max_retries} attempts. Last error code: {proc.returncode}")

    # Extract bundle
    progress.value = 50
    status_label.value = 'Extracting bundle...'
    print("Extracting bundle...")
    !tar -xzf {file_name}

    # Move Fiji and Java to working directory
    progress.value = 60
    status_label.value = 'Moving files...'
    !mv Fiji ../
    !mv jdk-latest ../
    print("Moved Fiji and Java runtime to working directory")

    # Safely merge bundle caches with existing user caches
    progress.value = 65
    status_label.value = 'Merging caches...'
    print("Merging bundle caches with local caches...")

    # Merge .jgo cache
    !mkdir -p ~/.jgo
    !cp -r .jgo/* ~/.jgo/ || true
    print("Merged .jgo cache")

    # Merge .m2 cache
    !mkdir -p ~/.m2
    !cp -r .m2/* ~/.m2/ || true
    print("Merged .m2 cache")

    # Clean up bundle directory and return to original location
    progress.value = 70
    status_label.value = 'Cleaning up...'
    os.chdir(original_dir)
    !rm -rf {bundle_dir}
    print("Bundle setup complete!")
else:
    print("Fiji already exists, skipping bundle setup")
```

--------------------------------

### Configure Virtual Display and Install PyImageJ

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/pyimagej-ai-guide.ipynb

Sets up a virtual display if none is detected, installs PyImageJ using pip, and initializes the ImageJ instance. Handles potential errors during display testing and initialization.

```python
progress.value = 80
status_label.value = 'Setting up virtual display...'
if "DISPLAY" not in os.environ:
    print("Setting up virtual display...")
    os.environ["DISPLAY"] = ":99"
    xvfb_process = subprocess.Popen(["Xvfb", ":99", "-screen", "0", "1024x768x24"])

    # Wait a moment for Xvfb to start
    time.sleep(2)

    # Test if display is working
    try:
        result = subprocess.run(["xdpyinfo"], capture_output=True, text=True, timeout=5)
        display_working = result.returncode == 0
        if display_working:
            print("✓ Virtual display working - using interactive mode")
            ui_mode = 'interactive'
        else:
            print("⚠ Virtual display failed - falling back to headless mode")
            ui_mode = 'headless'
    except (subprocess.TimeoutExpired, FileNotFoundError):
        print("⚠ Cannot test display - falling back to headless mode")
        ui_mode = 'headless'
else:
    print(f"Display already configured: {os.environ['DISPLAY']}")

# Install PyImageJ if not already installed
progress.value = 85
status_label.value = 'Installing PyImageJ...'
try:
    import imagej
    print("PyImageJ already installed")
except ImportError:
    print("Installing PyImageJ...")
    %pip install pyimagej
    import imagej

# This line avoids linting warnings about being unbounded vars
ij: Any = ij if 'ij' in globals() or 'ij' in locals() else None
ui_mode: Any = ui_mode if 'ui_mode' in globals() or 'ui_mode' in locals() else None

# Initialize PyImageJ (no further downloads needed!)
progress.value = 87.5
status_label.value = 'Initializing PyImageJ...'
try:
    # Check if ImageJ is already initialized
    ij.getVersion()
    print(f"PyImageJ already initialized with ImageJ {ij.getVersion()}")
except AttributeError:
    # ij variable is None, safe to initialize
    print(f"Initializing PyImageJ in {ui_mode} mode...")
    ij = imagej.init('./Fiji', mode=ui_mode)
    print(f"PyImageJ initialized with ImageJ {ij.getVersion()}")
except Exception as e:
    # ij exists but might be in bad state, reinitialize
    print(f"Reinitializing PyImageJ (previous state: {e})")
    ij = imagej.init('./Fiji', mode=ui_mode)
    print(f"PyImageJ initialized with ImageJ {ij.getVersion()}")

if ij is not None:
    progress.value = 97
    print("✅ PyImageJ is ready to use! The 'ij' variable contains your ImageJ instance.")
    print(f"UI Mode: {ui_mode}")
    if ui_mode == 'interactive':
        print("💡 Interactive mode enables RoiManager and other GUI features")
    else:
        print("💡 Headless mode - use ij.py.show() for image display")
```

--------------------------------

### Setup Fiji Bundle for PyImageJ

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/pyimagej-ai-guide.ipynb

Downloads and sets up a Fiji bundle for PyImageJ, initializing the `ij` variable for ImageJ interaction. This process can take a few minutes.

```python
%%capture bundle_setup
#@title 🏝️ Setup Fiji Bundle { display-mode: "form" }
#@markdown PyImageJ connects ImageJ to the Python ecosystem, but we still need an *ImageJ application* with all our image analysis goodness.
#@markdown
#@markdown In this cell we download a "local" copy of the selected Fiji bundle, which we access via PyImageJ. This lets us use all of the plugins you get when using Fiji normally. Note that this can take **a few minutes**.
#@markdown
#@markdown 💡 Tip: this setup will initialize the **`ij` variable** -  your main interface to ImageJ (e.g., `ij.io().open()`, `ij.op().math()`)

# --UPDATE: pin to particular release--
bundle_id= "20251023"

import os
import subprocess
import time
import re
from typing import Any

# Set target bundle (update as desired from https://github.com/fiji/fiji-builds/releases)
bundle_name = "fiji-py-colab-" + bundle_id

progress.value = 8
status_label.value = 'Preparing to download Fiji...'
```

--------------------------------

### Install System Dependencies and Set Up Virtual Display

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/custom-pyimagej-ai-guide.ipynb

Installs necessary system dependencies like Maven and Xvfb if not present. It also sets up a virtual display environment for PyImageJ, defaulting to headless mode if the display cannot be confirmed.

```python
# Install system dependencies only if needed
!command -v mvn >/dev/null 2>&1 && command -v xdpyinfo >/dev/null 2>&1 || (apt-get update && apt-get install -y maven xvfb x11-utils
    x11-utils libxext6 libxrender1 libxtst6 libxi6 fonts-dejavu)

# Start up a virtual display only if needed
if "DISPLAY" not in os.environ:
    print("Setting up virtual display...")
    os.environ["DISPLAY"] = ":99"
    xvfb_process = subprocess.Popen(["Xvfb", ":99", "-screen", "0", "1024x768x24"])

    # Wait a moment for Xvfb to start
    time.sleep(2)

    # Test if display is working
    try:
        result = subprocess.run(["xdpyinfo"], capture_output=True, text=True, timeout=5)
        display_working = result.returncode == 0
        if display_working:
            print("✓ Virtual display working - using interactive mode")
            ui_mode = 'interactive'
        else:
            print("⚠ Virtual display failed - falling back to headless mode")
            ui_mode = 'headless'
    except (subprocess.TimeoutExpired, FileNotFoundError):
        print("⚠ Cannot test display - falling back to headless mode")
        ui_mode = 'headless'
else:
    print(f"Display already configured: {os.environ['DISPLAY']}")
```

--------------------------------

### PyImageJ Async Analysis Plugin Example

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/personas/activities/coding_advanced.md

Demonstrates how to define a custom asynchronous analysis plugin by inheriting from AnalysisPlugin and implementing the process method. This example simulates a CPU-intensive task.

```python
class ImageSegmentationPlugin(AnalysisPlugin):
    _cpu_intensive = True  # Mark as CPU-intensive
    
    @property
    def name(self) -> str:
        return "segmentation"
    
    async def process(self, data: Any, context: Dict[str, Any]) -> Any:
        # Simulate CPU-intensive segmentation
        await asyncio.sleep(0.1)  # Simulate processing time
        return {"segmented": True, "regions": 42}

# Framework usage
framework = AsyncAnalysisFramework(max_workers=8)
framework.register_plugin(ImageSegmentationPlugin())

# Process batch of images
async def main():
    data = [f"image_{i}.tif" for i in range(100)]
    results = await framework.process_batch(data, ["segmentation"])
    performance = framework.get_performance_report()
    print(f"Processed {len(results)} items")
    print(f"Performance: {performance}")

# asyncio.run(main())

```

--------------------------------

### Verify PyImageJ Setup

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/pyimagej-ai-guide.ipynb

Performs a quick verification of the PyImageJ setup by printing the ImageJ version, legacy mode status, and UI mode.

```python
#@title ✅ Verify Setup { display-mode: "form" }
#@markdown This double-checks that PyImageJ was setup correctly

status_label.value = 'Verifying PyImageJ functionality...'

# Quick verification that PyImageJ is working
print("=== Setup Verification ===")
print(f"✅ ImageJ version: {ij.getVersion()}")
print(f"✅ Legacy mode: {'Active' if ij.legacy.isActive() else 'Inactive'}")
print(f"✅ UI mode: {ui_mode}")
```

--------------------------------

### Initialize ImageJ and Get Version

Source: https://github.com/imagej/pyimagej/blob/main/doc/12-Troubleshooting.ipynb

Initializes ImageJ and prints its version. This is a common first step in PyImageJ notebooks.

```python
import imagej

# initialize ImageJ
ij = imagej.init()
print(f"ImageJ2 version: {ij.getVersion()}")
```

--------------------------------

### Test PyImageJ Installation

Source: https://github.com/imagej/pyimagej/blob/main/doc/Install.md

Verifies the PyImageJ installation by initializing ImageJ and printing its version. Expected output is '2.14.0'.

```python
python -c 'import imagej; ij = imagej.init("2.14.0"); print(ij.getVersion())'
```

--------------------------------

### Install X11 packages for Xvfb on fresh Linux servers

Source: https://github.com/imagej/pyimagej/blob/main/doc/Headless.md

On fresh Linux servers without a graphical environment, install additional X11 related packages along with Xvfb for PyImageJ to function correctly with virtual displays.

```console
$ sudo apt install libxrender1 libxtst6 libxi6 fonts-dejavu fontconfig
```

--------------------------------

### Install System Dependencies

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/pyimagej-ai-guide.ipynb

Installs Maven and Xvfb (X virtual framebuffer) along with other necessary X11 utilities and fonts if they are not already present on the system. This is crucial for GUI applications and build tools.

```bash
# Install system dependencies only if needed
progress.value = 75
status_label.value = 'Installing system dependencies...'
!command -v mvn >/dev/null 2>&1 && command -v xdpyinfo >/dev/null 2>&1 || (apt-get update && apt-get install -y maven xvfb x11-utils libxext6 libxrender1 libxtst6 libxi6 fonts-dejavu)
```

--------------------------------

### Start Python Interpreter from Project Root

Source: https://github.com/imagej/pyimagej/blob/main/doc/Development.md

Use this command to start a Python interpreter from the project root when testing local changes to PyImageJ. It leverages `uv` for package management.

```bash
uv run python
```

--------------------------------

### Install PyImageJ with Conda/Mamba

Source: https://github.com/imagej/pyimagej/blob/main/README.md

Use this snippet to create a new conda environment and install PyImageJ using Mamba. Ensure Mamba is installed in your base environment first.

```bash
conda install mamba -n base -c conda-forge
mamba create -n pyimagej -c conda-forge pyimagej
conda activate pyimagej
```

--------------------------------

### Dynamic Installation in Jupyter Notebook

Source: https://github.com/imagej/pyimagej/blob/main/doc/Install.md

Installs PyImageJ and OpenJDK 11 within a Jupyter notebook environment using mamba. Sets JAVA_HOME for the current session.

```python
import sys, os
prefix = sys.prefix.replace("\\", "/") # Handle Windows Paths
%mamba install --yes --prefix {prefix} -c conda-forge pyimagej openjdk=11
jvm_lib_path = [sys.prefix, 'lib', 'jvm']

# platform specific JVM lib path locations
if sys.platform == "win32":
    jvm_lib_path.insert(1, 'Library')
os.environ['JAVA_HOME'] = os.sep.join(jvm_lib_path)
```

--------------------------------

### Local Adaptive Thresholding Setup

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/imagej_ops.md

Provides the setup code for local adaptive thresholding in ImageJ Ops, requiring the import of `RectangleShape` and definition of a neighborhood shape.

```python
from scyjava import jimport
RectangleShape = jimport('net.imglib2.algorithm.neighborhood.RectangleShape')
shape = RectangleShape(radius=15, skip_center=False)
```

--------------------------------

### Initialize PyImageJ

Source: https://github.com/imagej/pyimagej/blob/main/doc/09-Working-with-Large-Images.ipynb

Initializes PyImageJ in interactive mode and prints the ImageJ2 version. Ensure PyImageJ is installed.

```python
import imagej

ij = imagej.init(mode='interactive')
print(f"ImageJ2 version: {ij.getVersion()}")
```

--------------------------------

### Initialize pyimagej with local plugins directory

Source: https://github.com/imagej/pyimagej/blob/main/doc/Initialization.md

Use local plugins by setting the 'plugins.dir' JVM option. This approach is an alternative to using a local ImageJ2 installation.

```python
import imagej
import scyjava
plugins_dir = '/Applications/Fiji.app/plugins'
scyjava.config.add_option(f'-Dplugins.dir={plugins_dir}')
ij = imagej.init()
```

--------------------------------

### Initialize ImageJ

Source: https://github.com/imagej/pyimagej/blob/main/doc/Classic-Segmentation.ipynb

Initializes the ImageJ environment. Use 'mode="interactive"' for interactive Fiji. Ensure ImageJ is installed and accessible.

```python
import imagej
import scyjava as sj

# initialize ImageJ
ij = imagej.init('sc.fiji:fiji', mode='interactive')
print(f"ImageJ version: {ij.getVersion()}")
```

--------------------------------

### Verify PyImageJ Setup and Load Image

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/custom-pyimagej-ai-guide.ipynb

Verifies the PyImageJ setup by checking the ImageJ version, legacy mode status, and UI mode. It also performs a simple test by loading and displaying the shape of a sample image from a URL.

```python
#@title ✅ Verify Your Setup { display-mode: "form" }
#@markdown This double-checks that PyImageJ was setup correctly. You can safely proceed to [🚀 Start Your Learning Journey](#scrollTo=_Start_Your_Learning_Journey)!

# Quick verification that PyImageJ is working
print("=== Setup Verification ===")
print(f"✅ ImageJ version: {ij.getVersion()}")
print(f"✅ Legacy mode: {'Active' if ij.legacy.isActive() else 'Inactive'}")
print(f"✅ UI mode: {ui_mode}")

# Simple test: load and display an image
test_dataset = ij.io().open('https://imagej.net/images/blobs.gif')
print(f"✅ Image loaded: {ij.py.from_java(test_dataset).shape}")
print("🎉 PyImageJ is ready! Ask Gemini what to try next.")
```

--------------------------------

### Initialize ImageJ and Get Version

Source: https://github.com/imagej/pyimagej/blob/main/doc/02-Working-with-Java-classes-and-Python.ipynb

Initialize ImageJ and retrieve its version. This sets up the environment for using ImageJ's Java API through PyImageJ.

```python
import imagej
from scyjava import jimport

# initialize ImageJ
ij = imagej.init()
print(f"ImageJ version: {ij.getVersion()}")
```

--------------------------------

### Setup Fiji Bundle for PyImageJ

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/custom-pyimagej-ai-guide.ipynb

Sets up a local copy of the Fiji bundle, which is necessary for PyImageJ to interface with ImageJ. This cell initializes the `ij` variable, your main interface to ImageJ.

```python
%%capture bundle_setup
#@title 🏝️ Setup Fiji Bundle { display-mode: "form" }
#@markdown PyImageJ connects ImageJ to the Python ecosystem, but we still need an *ImageJ application* with all our image analysis goodness.
#@markdown
#@markdown In this cell we set up a "local" copy of the selected Fiji bundle, which we access via PyImageJ. This lets us use all of the plugins you get when using Fiji normally.
#@markdown
#@markdown 💡 Tip: this setup will initialize the **`ij` variable** -  your main interface to ImageJ (e.g., `ij.io().open()`, `ij.op().math()`)

bundle_id= "20250912" #@param ["20250912"]

import os
import subprocess
import time
from typing import Any

# Set target bundle (update as desired from https://github.com/fiji/fiji-builds/releases)
bundle_name = "pyimagej-" + bundle_id

# Only process bundle if Fiji doesn't already exist
if not os.path.exists("Fiji"):

    print("Setting up PyImageJ bundle...")

    # Work in a safe bundle directory to avoid conflicts with existing caches
    bundle_dir = "pyimagej_bundle"
    original_dir = os.getcwd()

    # Create and enter bundle directory
    os.makedirs(bundle_dir, exist_ok=True)
    os.chdir(bundle_dir)

    # Download bundle
    print("Downloading PyImageJ bundle...")
    file_name = "{bundle_name}.tar.gz".format(bundle_name=bundle_name)
    url = "https://github.com/fiji/fiji-builds/releases/download/{bundle_name}/{bundle_name}.tar.gz".format(bundle_name=bundle_name)
    
    # Keep trying until the file is complete
    while True:
      proc = subprocess.run(
        ["wget", "-c", url, "-O", file_name],
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE
      )
      if proc.returncode == 0:
        print("Download finished successfully.")
        break
      else:
        print("Download interrupted (return code: {}). Retrying in 10 seconds...".format(proc.returncode))
        # You can inspect proc.stdout / proc.stderr for debugging if you want
        time.sleep(10)

    # Extract bundle
    print("Extracting bundle...")
    !tar -xzf {file_name}

    # Move Fiji and Java to working directory
    !mv Fiji ../
    !mv jdk-latest ../
    print("Moved Fiji and Java runtime to working directory")

    # Safely merge bundle caches with existing user caches
    print("Merging bundle caches with local caches...")

    # Merge .jgo cache
    !mkdir -p ~/.jgo
    !cp -r .jgo/* ~/.jgo/ || true
    print("Merged .jgo cache")

    # Merge .m2 cache
    !mkdir -p ~/.m2
    !cp -r .m2/* ~/.m2/ || true
    print("Merged .m2 cache")

    # Clean up bundle directory and return to original location
    os.chdir(original_dir)
    !rm -rf {bundle_dir}
    print("Bundle setup complete!")
else:
    print("Fiji already exists, skipping bundle setup")

# Set up Java environment
if "JAVA_HOME" not in os.environ:
    java_home = !find ./jdk-latest/linux64 -name "*jdk*" -type d
    os.environ['JAVA_HOME'] = java_home[0]
    print(f"Set JAVA_HOME to: {os.environ['JAVA_HOME']}")
```

--------------------------------

### Initialize PyImageJ

Source: https://github.com/imagej/pyimagej/blob/main/doc/GLCM.ipynb

Initializes the PyImageJ environment. Ensure ImageJ is installed and accessible. `add_legacy=False` is used to disable legacy support.

```python
import imagej
import matplotlib.pyplot as plt
import pandas as pd
from matplotlib import patches

ij = imagej.init(add_legacy=False)
print(f"ImageJ2 version: {ij.getVersion()}")
```

--------------------------------

### Initialize ImageJ in Headless Mode

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/environments/env_headless.md

Use `imagej.init()` for headless initialization. The default call initializes the latest ImageJ2 version. You can specify a version, use a Fiji distribution, or point to a local installation.

```python
ij = imagej.init()
```

```python
ij = imagej.init('2.14.0')
```

```python
ij = imagej.init('sc.fiji:fiji')
```

```python
ij = imagej.init('/path/to/Fiji.app')
```

--------------------------------

### Initialize ImageJ2 and Print Version

Source: https://github.com/imagej/pyimagej/blob/main/doc/Deconvolution.ipynb

Initializes ImageJ2 with legacy disabled and prints the version. Use this to start a workflow that only requires ImageJ2 and imagej-ops.

```python
import imagej
import matplotlib.pyplot as plt

ij = imagej.init(add_legacy=False)
print(f"ImageJ2 version: {ij.getVersion()}")
```

--------------------------------

### ImageJ Thresholding Workflow Example

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/imagej1_api.md

Demonstrates a typical workflow for thresholding an image in ImageJ 1.x using pyimagej. This includes loading an image, applying auto thresholding, retrieving threshold values, and creating a binary mask.

```python
# Load image
img = ij.IJ.openImage("https://imagej.net/images/blobs.gif")

# Apply auto threshold
ij.IJ.setAutoThreshold(img, "Default dark")

# Get threshold values that were chosen
ip = img.getProcessor()
lower = ip.getMinThreshold()
upper = ip.getMaxThreshold()
print(f"Threshold range: {lower} - {upper}")

# Create binary mask
binary = img.duplicate()
binary.setTitle("Binary Mask")
ij.IJ.setAutoThreshold(binary, "Default dark")
ij.IJ.run(binary, "Convert to Mask", "")

# Now binary is a true binary image (0 or 255 pixels)
# Can use for measurements, particle analysis, etc.
```

--------------------------------

### Get Help for an Operation

Source: https://github.com/imagej/pyimagej/blob/main/doc/12-Troubleshooting.ipynb

Use `ij.op().help()` to retrieve detailed information about available operations and their signatures. This is useful for understanding how to use specific ImageJ Ops.

```python
print(ij.op().help('multiply'))
```

--------------------------------

### Run Macro with Arguments

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/pyimagej_core.md

Example of executing an ImageJ macro with defined input arguments and retrieving output. The macro defines its arguments using '#@ String' and '#@ int' syntax.

```python
macro = """
#@ String name
#@ int age
#@output String message
message = name + " is " + age + " years old."
"""
args = {
    "name": "Alice",
    "age": 30
}
result = ij.py.run_macro(macro, args)
print(result["message"])  # Access output
```

--------------------------------

### Initialize ImageJ2 Gateway and Display Image

Source: https://github.com/imagej/pyimagej/blob/main/doc/api.rst

This snippet shows how to initialize an ImageJ2 gateway, load an image from a URL, convert it to an xarray object, and display it using matplotlib. Ensure the 'imagej' library is installed.

```python
# Create an ImageJ2 gateway with the newest available version of ImageJ2.
import imagej
ij = imagej.init()

# Load an image.
image_url = 'https://imagej.net/images/clown.png'
jimage = ij.io().open(image_url)

# Convert the image from ImageJ2 to xarray, a package that adds
# labeled datasets to numpy (http://xarray.pydata.org/en/stable/).
image = ij.py.from_java(jimage)

# Display the image (backed by matplotlib).
ij.py.show(image, cmap='gray')
```

--------------------------------

### Install PyImageJ via Pip

Source: https://github.com/imagej/pyimagej/blob/main/doc/Install.md

Installs the PyImageJ package using pip. It is recommended to do this within a virtual environment.

```bash
pip install pyimagej
```

--------------------------------

### Initialize PyImageJ and Run Plugins

Source: https://github.com/imagej/pyimagej/blob/main/doc/Install.md

Initialize ImageJ in headless mode, retrieve its version, open an image, and then run ImageJ plugins with specified parameters. Note that 'Filter Rank' is a placeholder and may not be a valid plugin.

```python
import imagej
    ij = imagej.init('/tmp/Fiji.app', mode='headless')
    print(ij.getVersion())
    imp = ij.IJ.openImage('http://imagej.net/images/blobs.gif')
    ij.py.run_plugin('Filter Rank', {'window': 3, 'randomise': True}, imp=imp)
    ij.IJ.resetMinAndMax(imp)
    ij.py.run_plugin('Enhance Contrast', {'saturated': 0.35}, imp=imp)
```

--------------------------------

### Install Cellpose and StarDist

Source: https://github.com/imagej/pyimagej/blob/main/doc/Cellpose-StarDist-Segmentation.ipynb

Installs TensorFlow, StarDist, and Cellpose using mamba and pip. This is a prerequisite for running the segmentation tasks.

```python
%%capture
!mamba install -y -c conda-forge tensorflow stardist
!pip install cellpose
```

--------------------------------

### Install Xvfb on Debian/Ubuntu

Source: https://github.com/imagej/pyimagej/blob/main/doc/Headless.md

Install the Xvfb package on Debian-based systems to enable virtual display functionality for headless GUI operations.

```console
$ sudo apt install xvfb
```

--------------------------------

### Install PyImageJ in Docker with Micromamba

Source: https://github.com/imagej/pyimagej/blob/main/doc/Install.md

A Dockerfile snippet using Micromamba-docker to install PyImageJ, Python 3.9, and OpenJDK 11. It also downloads and extracts Fiji.

```dockerfile
# Micromamba-docker @ https://github.com/mamba-org/micromamba-docker
FROM mambaorg/micromamba:1.0.0

# Retrieve dependencies
USER root
RUN apt-get update
RUN apt-get install -y wget unzip > /dev/null && rm -rf /var/lib/apt/lists/* > /dev/null
RUN micromamba install -y -n base -c conda-forge \
        python=3.9\
        pyimagej  \
        openjdk=11 && \
    micromamba clean --all --yes
ENV JAVA_HOME="/usr/local"
# Set MAMVA_DOCKERFILE_ACTIVATE (otherwise python will not be found)
ARG MAMBA_DOCKERFILE_ACTIVATE=1  
# Retrieve ImageJ and source code
RUN wget https://downloads.imagej.net/fiji/latest/fiji-linux64.zip &> /dev/null
RUN unzip fiji-linux64.zip > /dev/null
RUN rm fiji-linux64.zip

```

--------------------------------

### Initialize and Run Particle Analyzer

Source: https://github.com/imagej/pyimagej/blob/main/doc/Puncta-Segmentation.ipynb

Sets up the ResultsTable, configures particle measurements, and runs the Analyze Particles plugin. Ensure the image is loaded and preprocessed before running.

```python
# get ResultsTable and set ParticleAnalyzer
rt = ij.ResultsTable.getResultsTable()
ParticleAnalyzer.setResultsTable(rt)

# set measurements
ij.IJ.run("Set Measurements...", "area center shape")

# run the analyze particle plugin
ij.py.run_plugin(plugin="Analyze Particles...", args="clear", imp=imp_thres)
```

--------------------------------

### Initialize PyImageJ with Specific Plugins (Specific Version)

Source: https://github.com/imagej/pyimagej/blob/main/doc/Initialization.md

Initializes PyImageJ with a list of specific plugins, using their specified versions.

```python
ij = imagej.init(['net.imagej:imagej:2.14.0', 'net.preibisch:BigStitcher:0.4.1'])
```

--------------------------------

### Initialize pyimagej with Fiji plugins

Source: https://github.com/imagej/pyimagej/blob/main/doc/Initialization.md

Create an ImageJ2 gateway including Fiji plugins by specifying 'sc.fiji:fiji'.

```python
import imagej
ij = imagej.init('sc.fiji:fiji')
```

```python
import imagej
ij = imagej.init('sc.fiji:fiji:2.14.0')
```

--------------------------------

### Initialize PyImageJ with Fiji Plugins (Specific Version)

Source: https://github.com/imagej/pyimagej/blob/main/doc/Initialization.md

Initializes PyImageJ with Fiji plugins using a specific version.

```python
ij = imagej.init('sc.fiji:fiji:2.14.0')
```

--------------------------------

### Initialize PyImageJ with Specific Plugins (Newest Version)

Source: https://github.com/imagej/pyimagej/blob/main/doc/Initialization.md

Initializes PyImageJ with a list of specific plugins, using their newest available versions.

```python
ij = imagej.init(['net.imagej:imagej', 'net.preibisch:BigStitcher'])
```

--------------------------------

### Install and Download File with gdown

Source: https://github.com/imagej/pyimagej/blob/main/doc/Google-Colab-Basics.md

Use this shell command to install the gdown package and download a file from Google Drive using its ID. Replace 'REPLACE_WITH_YOUR_FILE_ID' with the actual file ID.

```shell
%%shell
pip install -q gdown
gdown https://drive.google.com/uc?id=REPLACE_WITH_YOUR_FILE_ID&export=download
```

--------------------------------

### Build HTML Documentation from Project Root

Source: https://github.com/imagej/pyimagej/blob/main/doc/Development.md

An alternative command to build the Sphinx-based documentation from the project root directory. Results are generated in `doc/_build/html`.

```bash
make docs
```

--------------------------------

### Collaborative Analysis System Setup

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/personas/activities/colab_intermediate.md

Configure parameters for a collaborative analysis system, defining the team member's role and the current stage of the analysis. This setup is part of a form-based interface for managing team workflows.

```python
# Challenge: Build a collaborative analysis workflow
#@title 🤝 Collaborative Analysis System { display-mode: "form" }
#@markdown Create a system for team-based research analysis

# TODO: Design form parameters for team collaboration
team_role = "Analyst" #@param ["Data Collector", "Analyst", "Reviewer", "Manager"]
analysis_stage = "Data Processing" #@param ["Data Collection", "Data Processing", "Analysis", "Review", "Publication"]
```

--------------------------------

### Run Script with Arguments

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/pyimagej_core.md

Demonstrates how to run a script (e.g., Python, Groovy, JavaScript) with arguments and capture its output. The script uses '#@ String' and '#@ int' for input and '#@output' for output.

```python
script = """
#@ String name
#@ int age
#@output String message
message = name + " is " + age + " years old."
"""
args = {
    "name": "Bob",
    "age": 25
}
result = ij.py.run_script("python", script, args)  # or "groovy", "javascript", etc.
print(result["message"])  # Dict-like access to outputs
```

--------------------------------

### Install and Use gdown for Google Drive Files

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/environments/env_colab.md

Install the gdown package and use it to download files from public Google Drive links. This is a recommended method for accessing data in Colab when direct web hosting is not feasible.

```python
# Install gdown if needed
%pip install gdown

# Download from public Google Drive link
import gdown
file_id = "1ABC...XYZ"  # Extract from share link
gdown.download(f"https://drive.google.com/uc?id={file_id}", "data.tif", quiet=False)
```

--------------------------------

### Initialize ImageJ Gateway (No Legacy Support)

Source: https://github.com/imagej/pyimagej/blob/main/doc/01-Starting-PyImageJ.ipynb

Initialize the ImageJ gateway without support for the original ImageJ. This uses the newest available versions.

```python
ij = imagej.init('net.imagej:imagej', add_legacy=False)
```

--------------------------------

### Initialize ImageJ Gateway (Fiji Plugins, Newest)

Source: https://github.com/imagej/pyimagej/blob/main/doc/01-Starting-PyImageJ.ipynb

Initialize the ImageJ gateway with Fiji plugins using the newest available versions. This is useful for accessing a wide range of ImageJ functionalities.

```python
ij = imagej.init('sc.fiji:fiji')
```

--------------------------------

### Manually create a virtual display with Xvfb

Source: https://github.com/imagej/pyimagej/blob/main/doc/Headless.md

Manually create a virtual frame buffer using Xvfb before starting your PyImageJ session. This involves exporting the DISPLAY environment variable and starting Xvfb with specified screen dimensions and color depth.

```console
$ export DISPLAY=:1
$ Xvfb $DISPLAY -screen 0 1400x900x16 &
```

--------------------------------

### Update Status of All Registered Nodes via HTTP GET

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/personas/activities/colab_advanced.md

Fetches the status of all registered nodes using asynchronous HTTP GET requests. Updates node's current load, status, and last heartbeat. Handles potential exceptions and sets node status to 'offline' if the request fails. Requires 'aiohttp' and 'datetime'. A 5-second timeout is applied for each status check.

```python
    async def update_node_status(self):
        """Update status of all registered nodes."""
        for node_id, node in self.nodes.items():
            try:
                async with aiohttp.ClientSession() as session:
                    async with session.get(
                        f"{node.endpoint_url}/status",
                        timeout=aiohttp.ClientTimeout(total=5)
                    ) as response:
                        if response.status == 200:
                            status_data = await response.json()
                            node.current_load = status_data.get('current_load', 0)
                            node.status = status_data.get('status', 'unknown')
                            node.last_heartbeat = datetime.now()
                        else:
                            node.status = 'offline'
            except Exception as e:
                self.logger.warning(f"Failed to update status for node {node_id}: {e}")
                node.status = 'offline'
```

--------------------------------

### Manage Slice Labels (ImageStack)

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/imagej1_api.md

Get or set the labels for individual slices within an ImageStack. Slice labels are 1-indexed.

```python
# Slice labels (1-indexed!)
label = stack.getSliceLabel(slice_num)
stack.setSliceLabel("Label", slice_num)
```

--------------------------------

### Initialize ImageJ in Headless Mode

Source: https://github.com/imagej/pyimagej/blob/main/doc/11-Working-with-the-original-ImageJ.ipynb

Initializes ImageJ in headless mode, which is PyImageJ's default. Use this for environments without a GUI. The `mode='headless'` argument is optional as it's the default.

```python
import imagej

# initialize ImageJ
ij = imagej.init(mode='headless')
print(f"ImageJ version: {ij.getVersion()}")
```

--------------------------------

### Initialize PyImageJ to a Specific Version

Source: https://github.com/imagej/pyimagej/blob/main/doc/Initialization.md

Specify a particular version of ImageJ2 for reproducibility. Includes a call to get the version after initialization.

```python
import imagej
ij = imagej.init('2.14.0')
ij.getVersion()
```

--------------------------------

### Initialize with Latest Fiji Version

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/environments/env_interactive.md

Initialize pyimagej with the latest available version of Fiji, including ImageJ 1.x. Use this when the latest features are desired and reproducibility is not critical.

```python
imagej.init('sc.fiji:fiji')
```

--------------------------------

### Get ROI Statistics

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/imagej1_api.md

Retrieves statistical measurements for a defined Region of Interest (ROI). Ensure the ROI is set on the image before calling.

```python
img.setRoi(roi)
stats = roi.getStatistics()  # Returns ImageStatistics
area = stats.area
mean = stats.mean
```

--------------------------------

### Initialize Distributed Research Platform

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/personas/activities/colab_advanced.md

Sets up a distributed research platform by initializing the platform and registering compute nodes. This is a foundational step for large-scale collaborative computing.

```python
platform = DistributedResearchPlatform()

# Register compute nodes (would be actual Colab instances)
node1 = ComputeNode(
    node_id="colab-gpu-1",
    endpoint_url="https://colab-instance-1.example.com",
    capabilities=["image_processing", "deep_learning"],
    current_load=0,
    max_concurrent_tasks=2,
    last_heartbeat=datetime.now()
)

# In real implementation, would register actual nodes
# await platform.register_node(node1)

print("🚀 Distributed Research Platform initialized")
print("📊 Platform ready for large-scale collaborative computing")
```

--------------------------------

### Build HTML Documentation with Makefile

Source: https://github.com/imagej/pyimagej/blob/main/doc/Development.md

Builds the Sphinx-based documentation for PyImageJ. Results are generated in the `doc/_build/html` directory. This command can be run from the `/docs` directory.

```bash
make html
```

--------------------------------

### Get and Check Threshold Values in ImageJ 1.x

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/imagej1_api.md

Retrieves the current minimum and maximum threshold values from an image processor. Checks if the image has been thresholded.

```python
# Get threshold values
ip = img.getProcessor()
lower = ip.getMinThreshold()
upper = ip.getMaxThreshold()
```

```python
# Check if thresholded
if ip.getMinThreshold() != ij.ImagePlus.NO_THRESHOLD:
    print(f"Image is thresholded: {lower} - {upper}")
```

--------------------------------

### Initialize ImageJ with Fiji

Source: https://github.com/imagej/pyimagej/blob/main/doc/07-Running-Macros-Scripts-and-Plugins.ipynb

Initializes ImageJ2 with Fiji plugins for use in PyImageJ. This is a prerequisite for running many ImageJ functionalities.

```python
import imagej

# initialize ImageJ2 with Fiji plugins
ij = imagej.init('sc.fiji:fiji')
print(f"ImageJ2 version: {ij.getVersion()}")
```

--------------------------------

### Get Java and Python Image Slice Shapes

Source: https://github.com/imagej/pyimagej/blob/main/doc/06-Working-with-Images.ipynb

Slices both Java and xarray images and prints their resulting shapes. Note that Java slices return an IntervalView.

```python
# slice the test data
java_slice = dataset[:, :, 1, 10]
python_slice = xarr[10, :, :, 1]

# print slice shape
print(f"java_slice: {java_slice.shape}")
print(f"python_slice: {python_slice.shape}")
```

--------------------------------

### Initialize PyImageJ in headless mode

Source: https://github.com/imagej/pyimagej/blob/main/doc/Headless.md

Initialize PyImageJ without arguments to use headless mode by default. This is useful for cloud computing nodes or servers without a display.

```python
import imagej
ij = imagej.init()
```

--------------------------------

### Initialize with Multiple Maven Endpoints (Latest Versions)

Source: https://github.com/imagej/pyimagej/blob/main/doc/llms/rulesets/environments/env_interactive.md

Initialize pyimagej with a list of Maven coordinates for ImageJ2 and its dependencies, using their latest available versions. This is useful for leveraging the newest features.

```python
imagej.init(['net.imagej:imagej', 'net.preibisch:BigStitcher'])
```

--------------------------------

### Load Image as NumPy Array with Scikit-image

Source: https://github.com/imagej/pyimagej/blob/main/doc/06-Working-with-Images.ipynb

Loads the `cells3d` dataset from scikit-image into a NumPy array. Use this to get image data into Python for further manipulation or conversion.

```python
import skimage
cells = skimage.data.cells3d()
dump_info(cells)
```

--------------------------------

### Initialize PyImageJ with GUI (Blocking)

Source: https://github.com/imagej/pyimagej/blob/main/doc/Initialization.md

Initializes PyImageJ with a graphical user interface. This mode is blocking.

```python
ij = imagej.init(mode='gui')
```

--------------------------------

### Get JVM Memory Information

Source: https://github.com/imagej/pyimagej/blob/main/doc/01-Starting-PyImageJ.ipynb

Retrieve information about the ImageJ application, including the JVM's available memory. The `True` argument requests detailed information.

```python
ij.getApp().getInfo(True)
```

--------------------------------

### Initialize ImageJ Headless

Source: https://github.com/imagej/pyimagej/blob/main/doc/Puncta-Segmentation.ipynb

Initializes ImageJ in headless mode with the legacy layer enabled. This is the first step for using PyImageJ.

```python
import imagej
import scyjava as sj

# initialize imagej
ij = imagej.init(mode='headless', add_legacy=True)
print(f"ImageJ version: {ij.getVersion()}")
```

--------------------------------

### Get Help for an ImageJ Op

Source: https://github.com/imagej/pyimagej/blob/main/doc/10-Using-ImageJ-Ops.ipynb

Retrieves detailed information about an ImageJ Op, including its signature and parameter requirements. This is crucial for understanding how to use an Op correctly.

```python
ij.op().help("filter.tubeness")
```

--------------------------------

### Enable Debug Logging in PyImageJ

Source: https://github.com/imagej/pyimagej/blob/main/doc/Troubleshooting.md

Add this to the beginning of your Python script to enable verbose internal logging to stderr. This is useful for diagnosing issues with Java dependency installation.

```python
import imagej.doctor
imagej.doctor.debug_to_stderr()
```

--------------------------------

### Load and Display Sample Image

Source: https://github.com/imagej/pyimagej/blob/main/doc/02-Working-with-Java-classes-and-Python.ipynb

Load a sample TIFF image using ImageJ's I/O capabilities and display it using PyImageJ's `show` function. This prepares an image for further processing.

```python
# load test image
dataset = ij.io().open('sample-data/test_image.tif')

# display test image (see the Working with Images for more info)
ij.py.show(dataset)
```

--------------------------------

### Create PyImageJ Conda Environment

Source: https://github.com/imagej/pyimagej/blob/main/doc/Install.md

Installs PyImageJ and OpenJDK 11 into a new mamba environment named 'pyimagej'. OpenJDK 8 or 11 is required, with 11 recommended.

```bash
mamba create -n pyimagej pyimagej openjdk=11
```