0
# PyImageJ
1

2
PyImageJ provides seamless integration between ImageJ2/ImageJ and Python, enabling developers to combine powerful ImageJ image processing capabilities with Python's scientific computing ecosystem including NumPy, SciPy, scikit-image, xarray, and matplotlib.
3

4
## Package Information
5

6
- **Package Name**: pyimagej
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install pyimagej`
10
- **Version**: 1.7.0
11

12
## Core Imports
13

14
```python
15
import imagej
16
```
17

18
## Basic Usage
19

20
```python
21
import imagej
22
import numpy as np
23

24
# Initialize ImageJ2 with the newest available version
25
ij = imagej.init()
26

27
# Load an image from URL
28
image_url = "https://imagej.net/images/clown.png"
29
jimage = ij.io().open(image_url)
30

31
# Convert the image from ImageJ2 to xarray
32
image_xarray = ij.py.from_java(jimage)
33

34
# Display the image (backed by matplotlib)
35
ij.py.show(image_xarray, cmap="gray")
36

37
# Convert Python data to ImageJ2 format
38
numpy_array = np.random.rand(100, 100)
39
dataset = ij.py.to_dataset(numpy_array)
40

41
# Run ImageJ2 operations
42
result = ij.op().filter().gauss(dataset, 2.0)
43

44
# Convert back to Python
45
result_array = ij.py.from_java(result)
46
```
47

48
## Architecture
49

50
PyImageJ operates through a gateway architecture that provides:
51

52
- **ImageJ2 Gateway**: Central access point to ImageJ2 services and API
53
- **JPype Bridge**: Low-level Java-Python interoperability via JVM
54
- **ScyJava Layer**: High-level Java object conversion and management
55
- **Conversion System**: Bidirectional translation between Python and Java data structures
56
- **Legacy Support**: Optional compatibility with original ImageJ (ij.*) API
57

58
The system maintains two primary data flow paths:
59
- **Java → Python**: ImageJ2/ImgLib2 objects converted to NumPy arrays and xarray DataArrays
60
- **Python → Java**: NumPy arrays and xarray DataArrays converted to ImageJ2 Datasets and ImgLib2 structures
61

62
## Capabilities
63

64
### ImageJ2 Gateway Initialization
65

66
Core functionality for initializing and configuring the ImageJ2 environment with various modes and settings. Supports local installations, specific versions, or automatic downloads.
67

68
```python { .api }
69
def init(
70
    ij_dir_or_version_or_endpoint=None,
71
    mode: Union[Mode, str] = Mode.HEADLESS,
72
    add_legacy: bool = True,
73
    headless=None
74
) -> "ImageJ2Gateway": ...
75

76
class Mode(Enum):
77
    GUI = "gui"
78
    HEADLESS = "headless" 
79
    INTERACTIVE = "interactive"
80

81
def when_imagej_starts(f) -> None: ...
82
```
83

84
[Gateway Initialization](./gateway-initialization.md)
85

86
### Data Conversion & Translation
87

88
Comprehensive conversion system for translating data between Python (NumPy, xarray, pandas) and Java (ImageJ2, ImgLib2, ImagePlus) formats with full metadata preservation.
89

90
```python { .api }
91
# Core conversion methods (via ij.py.*)
92
def from_java(data): ...
93
def to_java(data, **hints): ...
94
def to_dataset(data, dim_order=None) -> "Dataset": ...
95
def to_img(data, dim_order=None) -> "Img": ...
96
def to_imageplus(data) -> "ImagePlus": ...
97
def to_xarray(data, dim_order=None) -> xr.DataArray: ...
98

99
# Type and format checking
100
def dtype(image_or_type): ...
101
```
102

103
[Data Conversion](./data-conversion.md)
104

105
### Image Processing Operations
106

107
Access to ImageJ2's extensive image processing capabilities through Python-friendly interfaces, including filters, mathematical operations, and analysis functions.
108

109
```python { .api }
110
# Mathematical operations (on RandomAccessibleInterval objects)
111
def __add__(self, other): ...
112
def __sub__(self, other): ...
113
def __mul__(self, other): ...
114
def __truediv__(self, other): ...
115

116
# Array-like operations
117
def __getitem__(self, key): ...
118
def squeeze(axis=None): ...
119
def transpose() -> "RandomAccessibleInterval": ...
120
```
121

122
[Image Processing](./image-processing.md)
123

124
### Script & Plugin Execution
125

126
Execute ImageJ macros, plugins, and scripts in various languages with argument passing and result retrieval capabilities.
127

128
```python { .api }
129
def run_macro(macro: str, args=None): ...
130
def run_plugin(plugin: str, args=None, ij1_style: bool = True, imp=None): ...
131
def run_script(language: str, script: str, args=None): ...
132
def argstring(args, ij1_style=True): ...
133
def jargs(*args): ...
134
```
135

136
[Script Execution](./script-execution.md)
137

138
### Image Display & Visualization
139

140
Display and visualization functions with matplotlib backend support for showing images, managing windows, and synchronizing data between ImageJ and Python.
141

142
```python { .api }
143
def show(image, cmap=None): ...
144
def sync_image(imp=None): ...
145
def active_dataset() -> "Dataset": ...
146
def active_imageplus(sync: bool = True) -> "ImagePlus": ...
147
def active_xarray(sync=True) -> xr.DataArray: ...
148
```
149

150
[Display & Visualization](./display-visualization.md)
151

152
### Environment & Diagnostics
153

154
Tools for environment configuration, troubleshooting, and system health checks to ensure proper PyImageJ operation.
155

156
```python { .api }
157
def checkup(output=print): ...
158
def debug_to_stderr(): ...
159
```
160

161
[Environment & Diagnostics](./environment-diagnostics.md)