Skip to content

Latest commit

 

History

History
237 lines (153 loc) · 9.39 KB

README.md

File metadata and controls

237 lines (153 loc) · 9.39 KB

GTTK ArcGIS Pro Toolbox Setup Guide

This guide provides detailed installation and configuration instructions for the GTTK ArcGIS Pro Python Toolbox.

Table of Contents

Prerequisites

  • ArcGIS Pro installed on your system
  • Administrator privileges for OSGeo4W installation
  • GTTK cloned or downloaded to your system

OSGeo4W Installation (Required Dependency)

CRITICAL PREREQUISITE: For the ArcGIS Pro Toolbox to function properly, you must have a standalone GDAL environment installed. The GDAL library bundled with ArcGIS Pro uses internal configuration settings that can override optimizations implemented through the GDAL Python API.

To work around this limitation, GTTK includes a specialized tool (gttk optimize-arc) that uses GDAL command-line utilities (gdal_translate, gdal_calc.py, gdalwarp, gdaladdo) executed via subprocess in an isolated OSGeo4W environment. This ensures optimal results while maintaining compatibility with ArcGIS Pro.

GTTK uses OSGeo4W, which provides access to the latest GDAL features and compression codecs while remaining isolated from ArcGIS Pro's internal GDAL. Another benefit of using the OSGeo4W installer is access to the free GIS software QGIS (see Installing QGIS via OSGeo4w below).

Note: For CLI users, gttk optimize-arc is also available as a standalone tool. See the main README for details.

Installation Instructions

Step 1: Download OSGeo4W Installer

Download the appropriate installer for your system:

Note: The v2 installer is the modern, recommended version. Avoid the legacy v1 installer unless you have specific requirements.

Step 2: Run the Installer

  1. Launch the downloaded osgeo4w-setup.exe with administrator privileges (right-click → "Run as administrator")

  2. Choose Installation Type:

    • Select "Express Install" for a quick, standard setup (recommended for most users)
    • OR select "Advanced Install" for granular package control (experienced users)

Step 3: Select Packages (Express Install)

If using Express Install, select:

  • ☑ QGIS Desktop - Includes QGIS and core dependencies
  • ☑ GDAL - Geospatial Data Abstraction Library (core requirement)

Step 3 Alternative: Select Packages (Advanced Install)

If using Advanced Install, you'll have more control over specific packages:

Required Packages:

  • ☑ gdal - Core GDAL library (select latest stable version)
  • ☑ gdal-python - Python bindings for GDAL
  • ☑ python3-core - Python interpreter

Recommended Packages:

  • ☑ qgis - QGIS Desktop application (see below)
  • ☑ qgis-grass-plugin - GRASS GIS integration (optional)
  • ☑ gdal-ecw - ECW format support (if needed)
  • ☑ gdal-mrsid - MrSID format support (if needed)

Advanced Codec Packages (for maximum compression options):

  • ☑ gdal-jxl - JPEG XL codec support
  • ☑ gdal-zstd - ZSTD compression support
  • ☑ gdal-lerc - LERC compression support

Step 4: Choose Installation Location

  • Default Location: C:\OSGeo4W (recommended)
  • Custom Location: Choose a path without spaces or special characters
  • Important: Remember this path - you'll need it for GTTK configuration

Step 5: Complete Installation

  1. Review selected packages
  2. Click "Next" to download and install
  3. Wait for installation to complete (may take several minutes)
  4. Click "Finish" when done

Post-Installation Configuration

Configure GTTK to Use OSGeo4W

After installation, update the GTTK configuration to point to your OSGeo4W installation:

  1. Open config.toml in the GTTK project root directory

  2. Locate the [paths] section:

    [paths]
# Path to OSGeo4W installation (required for ArcGIS Toolbox)
osgeo4w = "C:/OSGeo4W"

  3. Update the osgeo4w path if you installed to a custom location:

    [paths]
osgeo4w = "C:/Your/Custom/Path/OSGeo4W"

Verify Installation

Open OSGeo4W Shell (search for it in the Start Menu) and run:

# Check GDAL version
gdalinfo --version

# Check available drivers
gdalinfo --formats

# Check Python GDAL bindings version
python3 -c "from osgeo import gdal; print(gdal.__version__)"

Expected output should show:

  • Long list of supported drivers including GTiff and COG
  • Python GDAL version matching the GDAL library (3.11+ or the latest available)

Installing QGIS via OSGeo4W

While QGIS is an excellent tool and valuable for GIS workflows, standalone QGIS installations may lack the complete OSGeo4W dependencies that GTTK requires. The OSGeo4W installer provides:

  • Complete GDAL Environment: All necessary GDAL libraries, tools, and dependencies
  • Latest Compression Codecs: Access to modern codecs like JPEG XL (JXL), ZSTD, and LERC
  • QGIS as an Option: Includes QGIS among selectable packages - you get both!
  • Python Bindings: GDAL Python bindings for scripting and automation
  • Consistent Updates: Centralized update mechanism for all geospatial tools
  • Proven Compatibility: Widely used in professional and government environments

Benefits of Having Both ArcGIS Pro and QGIS:

  • Access to both proprietary and open-source toolsets
  • QGIS excels at certain tasks (e.g., styling, PostgreSQL/PostGIS integration, raster modeling with GDAL, etc.)
  • ArcGIS provides a wide suite of industry- and government-adopted mapping tools and the ArcPy environment (used by GTTK's Toobox)
  • Support for analytical workflows locked behind ArcGIS Pro extensions (e.g. Spatial Analyst) requiring additional licensing
  • Access to hundreds of community-developed plugins supporting unique tools
  • Open-source transparency and community support

Troubleshooting

Common Issues and Solutions:

  1. "GDAL not found" error in ArcGIS Pro Toolbox:

    • Verify osgeo4w path in config.toml points to the correct location
    • Ensure path points to the OSGeo4W root directory (e.g., C:/OSGeo4W)
    • Restart ArcGIS Pro after changing configuration

  2. "Missing codec" errors (JXL, ZSTD, etc.):

    • Run OSGeo4W installer again and select advanced codec packages
    • Verify packages are installed: check C:\OSGeo4W\bin\gdal\plugins

  3. Permission errors during installation:

    • Run installer as administrator
    • If on a managed corporate/government system, contact IT department
    • Consider installing to user-writable directory if needed

  4. PATH conflicts with other GDAL installations:

    • GTTK uses explicit path configuration to avoid conflicts
    • Do NOT add OSGeo4W to system PATH if you have other GDAL installations
    • GTTK will use the path specified in config.toml

Getting Help:

Python Environment Setup

CRITICAL DEPENDENCY: The tifffile module is required for GTTK to function properly. This package is not included in the default ArcGIS Pro arcgispro-py3 conda environment and must be installed in a custom environment.

Setting Up Your Environment

  1. In ArcGIS Pro, click on the Project menu and open the Package Manager. This manages the Python ArcPy conda environment(s). The pre-installed, default environment is arcgispro-py3.

  2. Clone the default environment into a new environment (e.g., arcgispro-gttk). This may take some time. If the clone fails, you may need to work with your IT department. If you already have a cloned environment (not arcgispro-py3), you may use that.

  3. Make the cloned environment active, then click on the Add Packages tab in the ArcGIS Pro Package Manager.

  4. Search for "tifffile" and install it. The package is available in the default conda channels.

  5. Ensure that the same environment is active when running GTTK tools from the toolbox.

Toolbox Setup Instructions

  1. Add Toolbox: In your ArcGIS Pro Project, open the Catalog pane, right-click Toolboxes and select Add Toolbox. Navigate to and select the toolbox folder in the project's root directory.

  2. Locate Toolbox: The GTTK_Toolbox.pyt toolbox will be visible in the Toolboxes folder. You can now expand it to use the tools.

    GTTK_Toolbox.pyt tool list

Quick Reference

Step Action
1 Install OSGeo4W with GDAL
2 Configure config.toml with OSGeo4W path
3 Clone ArcGIS Pro Python environment
4 Install tifffile in cloned environment
5 Add toolbox to ArcGIS Pro project