0
# Gateway Initialization
1

2
Core functionality for initializing and configuring the ImageJ2 environment. The gateway serves as the primary interface to ImageJ2 services and provides access to all ImageJ functionality from Python.
3

4
## Capabilities
5

6
### ImageJ2 Gateway Creation
7

8
Initialize ImageJ2 environment with configurable options for deployment scenarios.
9

10
```python { .api }
11
def init(
12
    ij_dir_or_version_or_endpoint=None,
13
    mode: Union[Mode, str] = Mode.HEADLESS,
14
    add_legacy: bool = True,
15
    headless=None
16
) -> "ImageJ2Gateway":
17
    """
18
    Initialize an ImageJ2 environment.
19
    
20
    Args:
21
        ij_dir_or_version_or_endpoint: Path to local ImageJ2 installation, 
22
            version string (e.g. "2.3.0"), endpoint (e.g. "sc.fiji:fiji"), 
23
            or list of Maven artifacts. Default uses latest ImageJ2.
24
        mode: Environment behavior mode - HEADLESS, GUI, or INTERACTIVE
25
        add_legacy: Whether to include original ImageJ (ij.*) support
26
        headless: Deprecated - use mode parameter instead
27
        
28
    Returns:
29
        ImageJ2 gateway instance providing access to all ImageJ functionality
30
    """
31
```
32

33
**Usage Examples:**
34

35
```python
36
# Use latest ImageJ2 in headless mode (default)
37
ij = imagej.init()
38

39
# Use specific version
40
ij = imagej.init("2.3.0")
41

42
# Use Fiji distribution
43
ij = imagej.init("sc.fiji:fiji")
44

45
# Use local installation
46
ij = imagej.init("/Applications/Fiji.app")
47

48
# Initialize with GUI mode
49
ij = imagej.init(mode=imagej.Mode.GUI)
50

51
# Use custom Maven artifacts
52
ij = imagej.init([
53
    "net.imagej:imagej:2.3.0",
54
    "net.imagej:imagej-legacy",
55
    "net.preibisch:BigStitcher"
56
])
57
```
58

59
### Environment Modes
60

61
Control how ImageJ2 operates in different deployment scenarios.
62

63
```python { .api }
64
class Mode(Enum):
65
    """ImageJ2 environment execution modes."""
66
    GUI = "gui"           # Start with GUI, display automatically, blocks execution
67
    HEADLESS = "headless" # No GUI, suitable for server/library usage  
68
    INTERACTIVE = "interactive" # GUI support available but not displayed automatically
69
    
70
    def __eq__(self, other): ...
71
```
72

73
**Mode Characteristics:**
74

75
- **HEADLESS**: Default mode, suitable for library usage and server deployments
76
- **GUI**: Shows ImageJ GUI automatically, blocks Python execution, terminates Python when ImageJ closes
77
- **INTERACTIVE**: GUI available via `ij.ui().showUI()`, works in Jupyter/IPython environments
78

79
### Startup Callbacks
80

81
Register functions to execute immediately after ImageJ2 initialization.
82

83
```python { .api }
84
def when_imagej_starts(f) -> None:
85
    """
86
    Register a function to be called immediately after ImageJ2 starts.
87
    
88
    Args:
89
        f: Single-argument function that receives the ImageJ2 Gateway
90
    """
91
```
92

93
**Usage Example:**
94

95
```python
96
def configure_imagej(ij):
97
    """Custom configuration applied after ImageJ2 starts."""
98
    ij.ui().showUI()
99
    print(f"ImageJ2 initialized with {ij.getVersion()}")
100

101
# Register callback before initialization
102
imagej.when_imagej_starts(configure_imagej)
103

104
# Initialize - callback will be executed
105
ij = imagej.init(mode=imagej.Mode.INTERACTIVE)
106
```
107

108
### Command Line Interface
109

110
Entry point for launching ImageJ from command line.
111

112
```python { .api }
113
def imagej_main():
114
    """Entry point for the 'imagej' console command."""
115
```
116

117
This function is automatically called when using the `imagej` command installed with the package:
118

119
```bash
120
# Launch ImageJ2 GUI
121
imagej
122

123
# Launch in headless mode  
124
imagej --headless
125
```
126

127
## Gateway Properties
128

129
Once initialized, the ImageJ2 gateway provides access to ImageJ services:
130

131
- `ij.py` - Python convenience methods (ImageJPython class)
132
- `ij.legacy` - Original ImageJ compatibility layer
133
- `ij.op()` - ImageJ2 Ops framework for image processing
134
- `ij.io()` - Image I/O services
135
- `ij.ui()` - User interface services
136
- `ij.convert()` - Data conversion services
137
- `ij.dataset()` - Dataset creation and management
138
- `ij.script()` - Script execution services
139

140
## Error Handling
141

142
Common initialization issues:
143

144
- **Missing Java**: PyImageJ requires Java 8+ and will download if needed
145
- **Version conflicts**: Specify exact versions to avoid Maven resolution issues  
146
- **Memory constraints**: Use JVM options for large image processing: `scyjava.config.add_option("-Xmx8g")`
147
- **Legacy conflicts**: Set `add_legacy=False` if experiencing ImageJ 1.x compatibility issues