Skip to content

Development

Jump to bottom
shred86 edited this page Jun 16, 2024 · 11 revisions

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:

  • Two configuration files exist, one for each tile (e.g., Ortho4XP_+32-113.cfg) and a global one (Ortho4XP.cfg). The global config file is the default config file that is referenced to create tile config files. It also contains some application specific settings.
  • 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.

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

Example of the global variables which are defined in the O4_Config_Utilities namespace. They can be referenced from other modules when O4_Config_Utils is imported: import O4_Config_Utils as CFG

App configuration variables:

UI.verbosity=1
UI.cleaning_level=1
OSM.overpass_server_choice=random
TILE.skip_downloads=False
TILE.skip_converts=False
TILE.max_convert_slots=4
IMG.check_tms_response=True
IMG.http_timeout=10
IMG.max_connect_retries=5
IMG.max_baddata_retries=5
OVL.ovl_exclude_pol=[0]
OVL.ovl_exclude_net=[]
custom_scenery_dir=
OVL.custom_overlay_src=
OVL.custom_overlay_src_alternate=

Tile configuration variables:

apt_smoothing_pix=8
road_level=1
road_banking_limit=0.5
lane_width=4.0
max_levelled_segs=200000
water_simplification=0.0
min_area=0.001
max_area=200.0
clean_bad_geometries=True
mesh_zl=19
curvature_tol=2.0
apt_curv_tol=0.5
apt_curv_ext=0.5
coast_curv_tol=1.0
coast_curv_ext=0.5
limit_tris=3.0
min_angle=10.0
sea_smoothing_mode=zero
water_smoothing=10
iterate=0
mask_zl=14
masks_width=100
masking_mode=sand
use_masks_for_inland=False
imprint_masks_to_dds=True
distance_masks_too=False
masks_use_DEM_too=False
masks_custom_extent=
default_website=
default_zl=16
zone_list=[]
cover_airports_with_highres=False
cover_extent=1.0
cover_zl=18
sea_texture_blur=0.0
water_tech=XP11 + bathy
ratio_water=0.25
ratio_bathy=1.0
normal_map_strength=1.0
terrain_casts_shadows=True
overlay_lod=25000
use_decal_on_terrain=False
custom_dem=
fill_nodata=True

Global tile configuration variables

global_apt_smoothing_pix=8
global_road_level=1
global_road_banking_limit=0.5
global_lane_width=4.0
global_max_levelled_segs=200000
global_water_simplification=0.0
global_min_area=0.001
global_max_area=200.0
global_clean_bad_geometries=True
global_mesh_zl=19
global_curvature_tol=2.0
global_apt_curv_tol=0.5
global_apt_curv_ext=0.5
global_coast_curv_tol=1.0
global_coast_curv_ext=0.5
global_limit_tris=3.0
global_min_angle=10.0
global_sea_smoothing_mode=zero
global_water_smoothing=10
global_iterate=0
global_mask_zl=14
global_masks_width=100
global_masking_mode=sand
global_use_masks_for_inland=False
global_imprint_masks_to_dds=True
global_distance_masks_too=False
global_masks_use_DEM_too=False
global_masks_custom_extent=
global_cover_airports_with_highres=False
global_cover_extent=1.0
global_cover_zl=18
global_sea_texture_blur=0.0
global_water_tech=XP11 + bathy
global_ratio_water=0.25
global_ratio_bathy=1.0
global_normal_map_strength=1.0
global_terrain_casts_shadows=True
global_overlay_lod=25000
global_use_decal_on_terrain=False
global_custom_dem=
global_fill_nodata=True
Clone this wiki locally