Development

The purpose of this page is to provide notes for users interested in modifying or helping develop Ortho4XP.

Formatting

With any new or revised functions and methods, typing, documentation strings and Black formatting is being used.

Using PyInstaller

PyInstaller is used to bundle Ortho4XP its dependencies into a single package allowing a user to run Ortho4XP without any additional setup.

The following arguments were used with PyInstaller to build the package:

Windows 11 (Command Prompt):

pyinstaller --noconfirm ^
    --paths=src ^
    --add-data="./Utils:./Ortho4XP_Data/Utils" ^
    --add-data="./Extents:./Ortho4XP_Data/Extents" ^
    --add-data="./Filters:./Ortho4XP_Data/Filters" ^
    --add-data="./Licence:./Ortho4XP_Data/Licence" ^
    --add-data="./Patches:./Ortho4XP_Data/Patches" ^
    --add-data="./Previews:./Ortho4XP_Data/Previews" ^
    --add-data="./Providers:./Ortho4XP_Data/Providers" ^
    --add-data="community_server.txt:./Ortho4XP_Data/" ^
    --hidden-import=PIL ^
    Ortho4XP.py

macOS 14.5:

pyinstaller --noconfirm \
    --paths=src \
    --add-data="./Utils:./Ortho4XP_Data/Utils" \
    --add-data="./Extents:./Ortho4XP_Data/Extents" \
    --add-data="./Filters:./Ortho4XP_Data/Filters" \
    --add-data="./Licence:./Ortho4XP_Data/Licence" \
    --add-data="./Patches:./Ortho4XP_Data/Patches" \
    --add-data="./Previews:./Ortho4XP_Data/Previews" \
    --add-data="./Providers:./Ortho4XP_Data/Providers" \
    --add-data="community_server.txt:./Ortho4XP_Data/" \
    --hidden-import=PIL \
    Ortho4XP.py

Linux (Debian):

pyinstaller --noconfirm \
    --paths=src \
    --add-data="./Utils:./Ortho4XP_Data/Utils" \
    --add-data="./Extents:./Ortho4XP_Data/Extents" \
    --add-data="./Filters:./Ortho4XP_Data/Filters" \
    --add-data="./Licence:./Ortho4XP_Data/Licence" \
    --add-data="./Patches:./Ortho4XP_Data/Patches" \
    --add-data="./Previews:./Ortho4XP_Data/Previews" \
    --add-data="./Providers:./Ortho4XP_Data/Providers" \
    --add-data="community_server.txt:./Ortho4XP_Data/" \
    --hidden-import=PIL \
    --collect-submodules=PIL \
    Ortho4XP.py

Note: Using -collect-submodules is required for Linux which pulls in an additional file _imagingmorph.cpython-312-x86_64-linux-gnu.so into _internal/PIL during the build process. For some reason, this is required on Linux or the map will not load in the Tile and management window.

When building the package on Windows, it has to be accomplished outside of a Python virtual environment (if used).

When building the package on macOS or Linux, it can be accomplished either outside or inside of a Python virtual environment.

For macOS, an additional step is required to get GDAL to work. Once the Ortho4XP package is built, copy the *.so files from your venv site-packages, /Users/user_name/Projects/Ortho4XP/venv/lib/python3.12/site-packages/osgeo and replace the ones in the package dist/Ortho4XP/_internal/osgeo folder. It's unknown at this time as to why this is required but was the only way to get GDAL to work properly.

Since each package is specific to the operating system and architecture, unnecessary files can be deleted before distribution to reduce file size. The current files that are being removed:

• The win, mac and/or lin folder inside the Ortho4XP/Utils directory, depending on which platform it's being built for.
• If building for Windows, removing the *.whl files that this forked version added in the win folder.
• Old folder inside Ortho4XP/Utils/mac folder since they are unused.

Notes

Data storage:

• Global variables within the O4_Config_Utils.py module which are often accessed within that module by making use of exec(), eval() and globals().
• self.v_ within O4_Config_Utils.py which is all of the Tkinter objects for widgets.
• self.v2_ within O4_Config_Utils.py which is the same as above except for the Global Config tab in the Ortho4XP Config window. This was added as a part of the config window update.

Some imports appear unused within the IDE, but they are actually used at execution or runtime based on the use of exec() and eval().