|
2 | 2 |
|
3 | 3 | # Python Scripting with Appose |
4 | 4 |
|
5 | | -This library provides a |
6 | | -[JSR-223-compliant](https://en.wikipedia.org/wiki/Scripting_for_the_Java_Platform) |
7 | | -scripting plugin for the [Python](https://python.org/) language, built on |
8 | | -the [appose](https://github.com/apposed/appose-python) Python package. |
9 | | - |
10 | | -It is implemented as a `ScriptLanguage` plugin for the [SciJava |
11 | | -Common](https://github.com/scijava/scijava-common) platform, which means that |
12 | | -in addition to being usable directly as a `javax.script.ScriptEngineFactory`, |
13 | | -it also provides some functionality on top. |
14 | | - |
15 | | -For a complete list of scripting languages available as part of the SciJava |
16 | | -platform, see the |
17 | | -[Scripting](https://github.com/scijava/scijava-common/wiki/Scripting) page on |
18 | | -the SciJava Common wiki. |
19 | | - |
20 | | -See also: |
21 | | -* [Python Scripting](https://imagej.net/scripting/python) on the ImageJ wiki. |
| 5 | +This library provides a `ScriptLanguage` plugin for the |
| 6 | +[SciJava Common](https://github.com/scijava/scijava-common) platform that runs |
| 7 | +scripts in [CPython](https://python.org/) (not Jython!), each in its own |
| 8 | +Python environment, using [Appose](https://github.com/apposed/appose). |
| 9 | + |
| 10 | +Scripts are ordinary SciJava scripts: they declare |
| 11 | +[script parameters](https://imagej.net/scripting/parameters) and can be run |
| 12 | +from the Script Editor or menus of ImageJ2/Fiji like any other script. |
| 13 | + |
| 14 | +## Writing a script |
| 15 | + |
| 16 | +```python |
| 17 | +#!appose-python |
| 18 | +#@script(env="myenv.toml") |
| 19 | + |
| 20 | +#@ Img image |
| 21 | +#@ double sigma |
| 22 | +#@output Img blurred |
| 23 | + |
| 24 | +from scipy.ndimage import gaussian_filter |
| 25 | + |
| 26 | +print(f"Blurring image of shape {image.shape}") |
| 27 | +blurred = gaussian_filter(image, sigma) |
| 28 | +``` |
| 29 | + |
| 30 | +* The `#!appose-python` line selects this script language, rather than |
| 31 | + another language handling `.py` files, such as Jython. |
| 32 | +* The `env` attribute points to an environment configuration file, resolved |
| 33 | + relative to the script's location. Any format Appose supports works: |
| 34 | + `pixi.toml`, `environment.yml`, `requirements.txt` or `pyproject.toml`. |
| 35 | + An optional `scheme` attribute (e.g. `scheme="pixi.toml"`) sets the format |
| 36 | + explicitly, which is useful when the file name does not reveal it. |
| 37 | +* The environment must include the `appose` Python package, plus `numpy` if |
| 38 | + the script uses images. |
| 39 | + |
| 40 | +See the `StarDist_cellcast.py` template for a complete example. |
| 41 | + |
| 42 | +## Environments |
| 43 | + |
| 44 | +The environment is built the first time a script needs it, which may take a |
| 45 | +while. Afterward, it is reused, both within the running application and across |
| 46 | +restarts. Environments are stored in the Appose environments directory |
| 47 | +(`~/.local/share/appose` by default), named after the configuration file. |
| 48 | +Scripts that share a configuration file share an environment. Editing the file |
| 49 | +causes the environment to be updated on the next run. |
| 50 | + |
| 51 | +Each script run starts a fresh Python process. |
| 52 | + |
| 53 | +## Inputs and outputs |
| 54 | + |
| 55 | +* Images (anything convertible to an Appose `NDArray`, such as an ImgLib2 |
| 56 | + `Img`) are passed via shared memory and appear in Python as |
| 57 | + NumPy arrays. Axes are in NumPy's usual order, which is the reverse of |
| 58 | + ImgLib2's: an image with X×Y dimensions `512×384` has NumPy shape |
| 59 | + `(384, 512)`. |
| 60 | +* Numbers, strings, booleans, lists and maps are passed as the corresponding |
| 61 | + Python values; files are passed as path strings. |
| 62 | +* Outputs are read from the Python variables of the same names after the |
| 63 | + script finishes. NumPy arrays are converted back to images; NumPy scalars |
| 64 | + become plain numbers. Outputs the script never assigns are left empty. |
| 65 | +* If the script declares no outputs and ends with an expression, its value |
| 66 | + becomes the script's result. |
| 67 | + |
| 68 | +Text printed to stdout and stderr appears in the Script Editor's output |
| 69 | +panes. Errors are reported with a Python traceback that refers to the |
| 70 | +script's own line numbers. |
0 commit comments