geoai-py 0.13.2__py2.py3-none-any.whl → 0.14.0__py2.py3-none-any.whl

geoai/__init__.py

@@ -2,7 +2,7 @@
 
 __author__ = """Qiusheng Wu"""
 __email__ = "giswqs@gmail.com"
-__version__ = "0.13.2"
+__version__ = "0.14.0"
 
 
 import os

geoai/train.py

@@ -433,7 +433,7 @@ def train_one_epoch(
             elapsed_time = time.time() - start_time
             if verbose:
                 print(
-                    f"Epoch: {epoch}, Batch: {i}/{len(data_loader)}, Loss: {losses.item():.4f}, Time: {elapsed_time:.2f}s"
+                    f"Epoch: {epoch + 1}, Batch: {i + 1}/{len(data_loader)}, Loss: {losses.item():.4f}, Time: {elapsed_time:.2f}s"
                 )
             start_time = time.time()
 

geoai/utils.py

@@ -3115,8 +3115,9 @@ def export_geotiff_tiles(
 
 def export_geotiff_tiles_batch(
     images_folder,
-    masks_folder,
-    output_folder,
+    masks_folder=None,
+    masks_file=None,
+    output_folder=None,
     tile_size=256,
     stride=128,
     class_value_field="class",
@@ -3128,21 +3129,34 @@ def export_geotiff_tiles_batch(
     skip_empty_tiles=False,
     image_extensions=None,
     mask_extensions=None,
+    match_by_name=True,
 ) -> Dict[str, Any]:
     """
-    Export georeferenced GeoTIFF tiles from folders of images and masks.
+    Export georeferenced GeoTIFF tiles from images and masks.
 
-    This function processes multiple image-mask pairs from input folders,
-    generating tiles for each pair. All image tiles are saved to a single
-    'images' folder and all mask tiles to a single 'masks' folder.
+    This function supports three mask input modes:
+    1. Single vector file covering all images (masks_file parameter)
+    2. Multiple vector files, one per image (masks_folder parameter)
+    3. Multiple raster mask files (masks_folder parameter)
 
-    Images and masks are paired by their sorted order (alphabetically), not by
-    filename matching. The number of images and masks must be equal.
+    For mode 1 (single vector file), specify masks_file path. The function will
+    use spatial intersection to determine which features apply to each image.
+
+    For mode 2/3 (multiple mask files), specify masks_folder path. Images and masks
+    are paired either by matching filenames (match_by_name=True) or by sorted order
+    (match_by_name=False).
+
+    All image tiles are saved to a single 'images' folder and all mask tiles to a
+    single 'masks' folder within the output directory.
 
     Args:
         images_folder (str): Path to folder containing raster images
-        masks_folder (str): Path to folder containing classification masks/vectors
-        output_folder (str): Path to output folder
+        masks_folder (str, optional): Path to folder containing classification masks/vectors.
+            Use this for multiple mask files (one per image or raster masks).
+        masks_file (str, optional): Path to a single vector file covering all images.
+            Use this for a single GeoJSON/Shapefile that covers multiple images.
+        output_folder (str, optional): Path to output folder. If None, creates 'tiles'
+            subfolder in images_folder.
         tile_size (int): Size of tiles in pixels (square)
         stride (int): Step size between tiles
         class_value_field (str): Field containing class values (for vector data)
@@ -3154,18 +3168,61 @@ def export_geotiff_tiles_batch(
         skip_empty_tiles (bool): If True, skip tiles with no features
         image_extensions (list): List of image file extensions to process (default: common raster formats)
         mask_extensions (list): List of mask file extensions to process (default: common raster/vector formats)
+        match_by_name (bool): If True, match image and mask files by base filename.
+            If False, match by sorted order (alphabetically). Only applies when masks_folder is used.
 
     Returns:
         Dict[str, Any]: Dictionary containing batch processing statistics
 
     Raises:
-        ValueError: If no images or masks found, or if counts don't match
+        ValueError: If no images found, or if masks_folder and masks_file are both specified,
+            or if neither is specified, or if counts don't match when using masks_folder with
+            match_by_name=False.
+
+    Examples:
+        # Single vector file covering all images
+        >>> stats = export_geotiff_tiles_batch(
+        ...     images_folder='data/images',
+        ...     masks_file='data/buildings.geojson',
+        ...     output_folder='output/tiles'
+        ... )
+
+        # Multiple vector files, matched by filename
+        >>> stats = export_geotiff_tiles_batch(
+        ...     images_folder='data/images',
+        ...     masks_folder='data/masks',
+        ...     output_folder='output/tiles',
+        ...     match_by_name=True
+        ... )
+
+        # Multiple mask files, matched by sorted order
+        >>> stats = export_geotiff_tiles_batch(
+        ...     images_folder='data/images',
+        ...     masks_folder='data/masks',
+        ...     output_folder='output/tiles',
+        ...     match_by_name=False
+        ... )
     """
 
     import logging
 
     logging.getLogger("rasterio").setLevel(logging.ERROR)
 
+    # Validate input parameters
+    if masks_folder is not None and masks_file is not None:
+        raise ValueError(
+            "Cannot specify both masks_folder and masks_file. Please use only one."
+        )
+
+    if masks_folder is None and masks_file is None:
+        raise ValueError(
+            "Must specify either masks_folder or masks_file for mask data source."
+        )
+
+    # Default output folder if not specified
+    if output_folder is None:
+        output_folder = os.path.join(images_folder, "tiles")
+
     # Default extensions if not provided
     if image_extensions is None:
         image_extensions = [".tif", ".tiff", ".jpg", ".jpeg", ".png", ".jp2", ".img"]
@@ -3202,30 +3259,88 @@ def export_geotiff_tiles_batch(
         pattern = os.path.join(images_folder, f"*{ext}")
         image_files.extend(glob.glob(pattern))
 
-    # Get list of mask files
-    mask_files = []
-    for ext in mask_extensions:
-        pattern = os.path.join(masks_folder, f"*{ext}")
-        mask_files.extend(glob.glob(pattern))
-
     # Sort files for consistent processing
     image_files.sort()
-    mask_files.sort()
 
     if not image_files:
         raise ValueError(
             f"No image files found in {images_folder} with extensions {image_extensions}"
         )
 
-    if not mask_files:
-        raise ValueError(
-            f"No mask files found in {masks_folder} with extensions {mask_extensions}"
-        )
+    # Handle different mask input modes
+    use_single_mask_file = masks_file is not None
+    mask_files = []
+    image_mask_pairs = []
 
-    if len(image_files) != len(mask_files):
-        raise ValueError(
-            f"Number of image files ({len(image_files)}) does not match number of mask files ({len(mask_files)})"
-        )
+    if use_single_mask_file:
+        # Mode 1: Single vector file covering all images
+        if not os.path.exists(masks_file):
+            raise ValueError(f"Mask file not found: {masks_file}")
+
+        # Load the single mask file once - will be spatially filtered per image
+        single_mask_gdf = gpd.read_file(masks_file)
+
+        if not quiet:
+            print(f"Using single mask file: {masks_file}")
+            print(
+                f"Mask contains {len(single_mask_gdf)} features in CRS: {single_mask_gdf.crs}"
+            )
+
+        # Create pairs with the same mask file for all images
+        for image_file in image_files:
+            image_mask_pairs.append((image_file, masks_file, single_mask_gdf))
+
+    else:
+        # Mode 2/3: Multiple mask files (vector or raster)
+        # Get list of mask files
+        for ext in mask_extensions:
+            pattern = os.path.join(masks_folder, f"*{ext}")
+            mask_files.extend(glob.glob(pattern))
+
+        # Sort files for consistent processing
+        mask_files.sort()
+
+        if not mask_files:
+            raise ValueError(
+                f"No mask files found in {masks_folder} with extensions {mask_extensions}"
+            )
+
+        # Match images to masks
+        if match_by_name:
+            # Match by base filename
+            image_dict = {
+                os.path.splitext(os.path.basename(f))[0]: f for f in image_files
+            }
+            mask_dict = {
+                os.path.splitext(os.path.basename(f))[0]: f for f in mask_files
+            }
+
+            # Find matching pairs
+            for img_base, img_path in image_dict.items():
+                if img_base in mask_dict:
+                    image_mask_pairs.append((img_path, mask_dict[img_base], None))
+                else:
+                    if not quiet:
+                        print(f"Warning: No mask found for image {img_base}")
+
+            if not image_mask_pairs:
+                raise ValueError(
+                    "No matching image-mask pairs found when matching by filename. "
+                    "Check that image and mask files have matching base names."
+                )
+
+        else:
+            # Match by sorted order
+            if len(image_files) != len(mask_files):
+                raise ValueError(
+                    f"Number of image files ({len(image_files)}) does not match "
+                    f"number of mask files ({len(mask_files)}) when matching by sorted order. "
+                    f"Use match_by_name=True for filename-based matching."
+                )
+
+            # Create pairs by sorted order
+            for image_file, mask_file in zip(image_files, mask_files):
+                image_mask_pairs.append((image_file, mask_file, None))
 
     # Initialize batch statistics
     batch_stats = {
@@ -3239,23 +3354,24 @@ def export_geotiff_tiles_batch(
     }
 
     if not quiet:
-        print(
-            f"Found {len(image_files)} image files and {len(mask_files)} mask files to process"
-        )
-        print(f"Processing batch from {images_folder} and {masks_folder}")
+        if use_single_mask_file:
+            print(f"Found {len(image_files)} image files to process")
+            print(f"Using single mask file: {masks_file}")
+        else:
+            print(f"Found {len(image_mask_pairs)} matching image-mask pairs to process")
+            print(f"Processing batch from {images_folder} and {masks_folder}")
         print(f"Output folder: {output_folder}")
         print("-" * 60)
 
     # Global tile counter for unique naming
     global_tile_counter = 0
 
-    # Process each image-mask pair by sorted order
-    for idx, (image_file, mask_file) in enumerate(
+    # Process each image-mask pair
+    for idx, (image_file, mask_file, mask_gdf) in enumerate(
         tqdm(
-            zip(image_files, mask_files),
+            image_mask_pairs,
             desc="Processing image pairs",
             disable=quiet,
-            total=len(image_files),
         )
     ):
         batch_stats["total_image_pairs"] += 1
@@ -3267,9 +3383,12 @@ def export_geotiff_tiles_batch(
             if not quiet:
                 print(f"\nProcessing: {base_name}")
                 print(f"  Image: {os.path.basename(image_file)}")
-                print(f"  Mask: {os.path.basename(mask_file)}")
+                if use_single_mask_file:
+                    print(f"  Mask: {os.path.basename(mask_file)} (spatially filtered)")
+                else:
+                    print(f"  Mask: {os.path.basename(mask_file)}")
 
-            # Process the image-mask pair manually to get direct control over tile saving
+            # Process the image-mask pair
             tiles_generated = _process_image_mask_pair(
                 image_file=image_file,
                 mask_file=mask_file,
@@ -3285,6 +3404,8 @@ def export_geotiff_tiles_batch(
                 all_touched=all_touched,
                 skip_empty_tiles=skip_empty_tiles,
                 quiet=quiet,
+                mask_gdf=mask_gdf,  # Pass pre-loaded GeoDataFrame if using single mask
+                use_single_mask_file=use_single_mask_file,
             )
 
             # Update counters
@@ -3362,10 +3483,16 @@ def _process_image_mask_pair(
     all_touched=True,
     skip_empty_tiles=False,
     quiet=False,
+    mask_gdf=None,
+    use_single_mask_file=False,
 ):
     """
     Process a single image-mask pair and save tiles directly to output directories.
 
+    Args:
+        mask_gdf (GeoDataFrame, optional): Pre-loaded GeoDataFrame when using single mask file
+        use_single_mask_file (bool): If True, spatially filter mask_gdf to image bounds
+
     Returns:
         dict: Statistics for this image-mask pair
     """
@@ -3433,11 +3560,36 @@ def _process_image_mask_pair(
         else:
             # Load vector class data
             try:
-                gdf = gpd.read_file(mask_file)
+                if use_single_mask_file and mask_gdf is not None:
+                    # Using pre-loaded single mask file - spatially filter to image bounds
+                    # Get image bounds
+                    image_bounds = box(*src.bounds)
+                    image_gdf = gpd.GeoDataFrame(
+                        {"geometry": [image_bounds]}, crs=src.crs
+                    )
 
-                # Always reproject to match raster CRS
-                if gdf.crs != src.crs:
-                    gdf = gdf.to_crs(src.crs)
+                    # Reproject mask if needed
+                    if mask_gdf.crs != src.crs:
+                        mask_gdf_reprojected = mask_gdf.to_crs(src.crs)
+                    else:
+                        mask_gdf_reprojected = mask_gdf
+
+                    # Spatially filter features that intersect with image bounds
+                    gdf = mask_gdf_reprojected[
+                        mask_gdf_reprojected.intersects(image_bounds)
+                    ].copy()
+
+                    if not quiet and len(gdf) > 0:
+                        print(
+                            f"  Filtered to {len(gdf)} features intersecting image bounds"
+                        )
+                else:
+                    # Load individual mask file
+                    gdf = gpd.read_file(mask_file)
+
+                    # Always reproject to match raster CRS
+                    if gdf.crs != src.crs:
+                        gdf = gdf.to_crs(src.crs)
 
                 # Apply buffer if specified
                 if buffer_radius > 0:

{geoai_py-0.13.2.dist-info → geoai_py-0.14.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geoai-py
-Version: 0.13.2
+Version: 0.14.0
 Summary: A Python package for using Artificial Intelligence (AI) with geospatial data
 Author-email: Qiusheng Wu <giswqs@gmail.com>
 License: MIT License
@@ -159,13 +159,17 @@ Comprehensive documentation is available at [https://opengeoai.org](https://open
 
 ## 📺 Video Tutorials
 
-Check out this 2-hour video tutorial on using GeoAI for geospatial data analysis and visualization.
+### GeoAI Made Easy: Learn the Python Package Step-by-Step (Beginner Friendly)
 
-[![cover](https://github.com/user-attachments/assets/1c14e651-65b9-41ae-b42d-3ad028b3eeb8)](https://youtu.be/jdK-cleFUkc)
+[![intro](https://github.com/user-attachments/assets/7e60ce05-573d-4d0d-9876-5289b87e5136)](https://youtu.be/VIl29Rca6zE&list=PLAxJ4-o7ZoPcvENqwaPa_QwbbkZ5sctZE)
 
-To learn more about GeoAI, you can watch the following video tutorials:
+### GeoAI Workshop: Unlocking the Power of GeoAI with Python
 
-[![cover](https://github.com/user-attachments/assets/3cde9547-ab62-4d70-b23a-3e5ed27c7407)](https://tinyurl.com/GeoAI-Tutorials)
+[![cover](https://github.com/user-attachments/assets/1c14e651-65b9-41ae-b42d-3ad028b3eeb8)](https://youtu.be/jdK-cleFUkc&list=PLAxJ4-o7ZoPcvENqwaPa_QwbbkZ5sctZE)
+
+### GeoAI Tutorials Playlist
+
+[![cover](https://github.com/user-attachments/assets/3cde9547-ab62-4d70-b23a-3e5ed27c7407)](https://www.youtube.com/playlist?list=PLAxJ4-o7ZoPcvENqwaPa_QwbbkZ5sctZE)
 
 ## 🤝 Contributing
 

{geoai_py-0.13.2.dist-info → geoai_py-0.14.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-geoai/__init__.py,sha256=4gwrJIsRBRP9mcJZMjX3TXxCtV_61kmf7ewRRkcDjiM,3851
+geoai/__init__.py,sha256=6XXPspLCl-xq93YsqtZKS9dzOI9nwDSzWGJvcxAZLT0,3851
 geoai/change_detection.py,sha256=XkJjMEU1nD8uX3-nQy7NEmz8cukVeSaRxKJHlrv8xPM,59636
 geoai/classify.py,sha256=0DcComVR6vKU4qWtH2oHVeXc7ZTcV0mFvdXRtlNmolo,35637
 geoai/detectron2.py,sha256=dOOFM9M9-6PV8q2A4-mnIPrz7yTo-MpEvDiAW34nl0w,14610
@@ -11,14 +11,14 @@ geoai/map_widgets.py,sha256=QLmkILsztNaRXRULHKOd7Glb7S0pEWXSK9-P8S5AuzQ,5856
 geoai/sam.py,sha256=O6S-kGiFn7YEcFbfWFItZZQOhnsm6-GlunxQLY0daEs,34345
 geoai/segment.py,sha256=yBGTxA-ti8lBpk7WVaBOp6yP23HkaulKJQk88acrmZ0,43788
 geoai/segmentation.py,sha256=7yEzBSKCyHW1dNssoK0rdvhxi2IXsIQIFSga817KdI4,11535
-geoai/train.py,sha256=QDG0z6VmvHmzJC-oujZb2YSxnNEBloU_lmEgSygPM6U,141818
-geoai/utils.py,sha256=lpyhytBeDLiqWz31syeRvpbT5AUn3cOblKU57uDD9sU,301265
+geoai/train.py,sha256=3uS95OTo3_KPuE9OhPRyFJ2PHFTlYUC4RVzJcLyzt4k,141826
+geoai/utils.py,sha256=4l5jewO4aRNRgeLDhrUFXwMA_CNBCSv8RkaCn3nN2p0,307795
 geoai/agents/__init__.py,sha256=NndUtQ5-i8Zuim8CJftCZYKbCvrkDXj9iLVtiBtc_qE,178
 geoai/agents/geo_agents.py,sha256=4tLntKBL_FgTQsUVzReP9acbYotnfjMRc5BYwW9WEyE,21431
 geoai/agents/map_tools.py,sha256=OK5uB0VUHjjUnc-DYRy2CQ__kyUIARSCPBucGabO0Xw,60669
-geoai_py-0.13.2.dist-info/licenses/LICENSE,sha256=vN2L5U7cZ6ZkOHFmc8WiGlsogWsZc5dllMeNxnKVOZg,1070
-geoai_py-0.13.2.dist-info/METADATA,sha256=wGO4OHdq1ubtroaqbEciKq1jHmJD8C_krbZTJByFP98,10345
-geoai_py-0.13.2.dist-info/WHEEL,sha256=JNWh1Fm1UdwIQV075glCn4MVuCRs0sotJIq-J6rbxCU,109
-geoai_py-0.13.2.dist-info/entry_points.txt,sha256=uGp3Az3HURIsRHP9v-ys0hIbUuBBNUfXv6VbYHIXeg4,41
-geoai_py-0.13.2.dist-info/top_level.txt,sha256=1YkCUWu-ii-0qIex7kbwAvfei-gos9ycyDyUCJPNWHY,6
-geoai_py-0.13.2.dist-info/RECORD,,
+geoai_py-0.14.0.dist-info/licenses/LICENSE,sha256=vN2L5U7cZ6ZkOHFmc8WiGlsogWsZc5dllMeNxnKVOZg,1070
+geoai_py-0.14.0.dist-info/METADATA,sha256=33j9XSDDCSdpU7PbuMP4zv7r50sTq-IdqJ4NnsSmjqo,10583
+geoai_py-0.14.0.dist-info/WHEEL,sha256=JNWh1Fm1UdwIQV075glCn4MVuCRs0sotJIq-J6rbxCU,109
+geoai_py-0.14.0.dist-info/entry_points.txt,sha256=uGp3Az3HURIsRHP9v-ys0hIbUuBBNUfXv6VbYHIXeg4,41
+geoai_py-0.14.0.dist-info/top_level.txt,sha256=1YkCUWu-ii-0qIex7kbwAvfei-gos9ycyDyUCJPNWHY,6
+geoai_py-0.14.0.dist-info/RECORD,,