Breaking Changes for Developer Toolkit and Smart Acquisition Toolkit
For the Developer Toolkit (OAD) and Smart Acquisition Toolkit (Experiment Feedback) there are possible breaking changes to scripts due to upgrade from IronPython 2.7 to IronPython 3.4. This upgrade introduces syntax changes that may render existing macros (.czmac or .py) incompatible with the new version.
For Experiment Feedback scripts you have to manually adapt the scripts to be compatible with IronPython 3 in case they are incompatible.
For other existing macros that will no longer work due to syntax differences between IronPython 2 and IronPython 3, a conversion tool is provided to update existing scripts for compatibility with the latest ZEN versions. To convert your macros you can either use the ZeissPython distribution which you can find in the ZEISS Microscopy Installer (ZMI), or you can use your own python distribution. You need the 2to3 tool, which reads Python 2.x source code and applies a series of fixers to transform it into valid Python 3.x code.
If you use the ZeissPython distribution available with the ZEISS Microscopy Installer, the 2to3 tool is located at located at C:\Program Files\Carl Zeiss\ZeissPython\Py23279.1\env. If you use your own Python distribution to run the conversion tools, you have to ensure that the 2to3 tool is available in your Python distribution. If necessary, it can be added using: pip install 2to3
If you are operating older and newer ZEN versions, you may need to use two different versions of your OAD scripts, one version that is compatible with IronPython 2 and another version of your script that is compatible with IronPython 3.
Converting OAD Macros in *.py Format
A conversion of macros in *.py format is done with the 2to3 tool. For a detailed documentation of the tool, see https://docs.python.org/3.10/library/2to3.html.
- The 2to3 tool is available on your PC.
- Open a command line tool.
- Command line is ready.
- Navigate to the location of your python.exe and run the Python 2to3 tool on your OAD macros with python ending (*.py) with the command
$ 2to3 file.py. For example, to convert a script called Amacrolib.py, type$ 2to3 Amacrolib.py. - The script is converted.
Converting OAD Macros in *.czmac Format
The python 2to3 tool cannot be applied directly to ZEN macro files in *.czmac format since they are XML files that contain Python code in one of its XML elements. For these macros we have provided a script on the ZEISS Github page which automatically converts an input macro (*.czmac) file from python2 to python3 syntax.
- The 2to3 tool is available on your PC.
- Go to the ZEISS Github page and download ZeissMacroConverter.py. To batch-convert all macro files in a specified directory, additionally download ZeissMacroBatchConverter.py. If you download the batch file, store it at the same location as the other file.
- The files for conversion are available.
- Use the command line and call the python script from command line with the parameters
-i(with the path to the file that needs to be converted) and-o(with the path to where the converted file needs to be stored, which can be the same as input file path). Example for converting a script called analysis time.czmac:D:\>python "D:\temp\macro\ZeissMacroConverter.py" "D:\temp\macro\analysis time.czmac" -o "D:\temp\macro\analysis time_converted.czmac" - The respective macro is converted.
- To batch-convert macros with the ZeissMacroBatchConverter.py, you need to specify the path to the root folder containing the OAD macro files, for example:
D:\>python "D:\temp\macro\ZeissMacroBatchConverter.py" "C:\OAD_Macros" - All macros in the folder are converted.
Special Notes
- There are some special cases which are not automatically converted. One of them is concatenating "str" and "bytes", in python2 this works, but in python3 you need to explicitly convert (encode/decode) one of them so that they are both "str" or "bytes"!
- Problem with trying to access a member called "None": In Python 3 you are not allowed to use access members called None. The example conversion macros linked above take care of this problem by using regex to replace the problematic parts as suggested here: https://github.com/IronLanguages/ironpython3/blob/v3.4.0/Documentation/upgrading-from-ipy2.md
- This is an example of the old and new syntax:
- #IronPython2 syntax:
set = Zen.Processing.Filter.Settings.GaussSetting()set.Dimension3rd.None - #IronPython3 syntax:
set = Zen.Processing.Filter.Settings.GaussSetting()set.Dimension3rd["None"]