### Install Project Dependencies

Source: https://github.com/ewanowara/geolocalization/blob/main/README.md

Installs all required packages for the project in an isolated environment. Ensure you have cloned the repository and are in the project directory.

```bash
git clone https://github.com/ewanowara/Geo-Localization.git && cd Geo-Localization

python3 -m venv glimpse_classification_env
pip install -r setup/requirements.txt
source glimpse_classification_env/bin/activate
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Clones the Geo-Localization repository and installs all necessary Python dependencies within a virtual environment. Ensure you have Python 3 and pip installed.

```bash
# Clone repository
git clone https://github.com/ewanowara/Geo-Localization.git && cd Geo-Localization

# Create and activate virtual environment
python3 -m venv glimpse_classification_env
source glimpse_classification_env/bin/activate

# Install dependencies (PyTorch, HuggingFace Transformers, vit-pytorch, etc.)
pip install -r setup/requirements.txt
```

--------------------------------

### Train Vision Transformer Model from Scratch

Source: https://github.com/ewanowara/geolocalization/blob/main/README.md

Initiates the training process for the Vision Transformer model from scratch. You can specify the GPU to use with `--cuda_base`.

```bash
python Train_ViT.py --cuda_base cuda:0
```

--------------------------------

### Download and Preprocess Training/Validation Images

Source: https://github.com/ewanowara/geolocalization/blob/main/README.md

Downloads image datasets (MP16 and YFCC25600) and assigns them to geo-cells. It also filters out images that were not successfully downloaded. Ensure you have sufficient disk space.

```bash
wget https://github.com/TIBHannover/GeoEstimation/releases/download/v1.0/mp16_urls.csv -O resources/mp16_urls.csv
wget https://github.com/TIBHannover/GeoEstimation/releases/download/pytorch/yfcc25600_urls.csv -O resources/yfcc25600_urls.csv 
python setup/download_images.py --output resources/images/mp16 --url_csv resources/mp16_urls.csv --shuffle
python setup/download_images.py --output resources/images/yfcc25600 --url_csv resources/yfcc25600_urls.csv --shuffle --size_suffix ""

# assign cell(s) for each image using the original meta information
wget https://github.com/TIBHannover/GeoEstimation/releases/download/v1.0/mp16_places365.csv -O resources/mp16_places365.csv
wget https://github.com/TIBHannover/GeoEstimation/releases/download/pytorch/yfcc25600_places365.csv -O resources/yfcc25600_places365.csv
python partitioning/assign_classes.py
# remove images that were not downloaded 
python setup/filter_by_downloaded_images.py
```

--------------------------------

### Download Flickr Images for Training

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Downloads MP-16 training images from a CSV of URLs. Images are shuffled, resized to 320 pixels with a 'z' suffix for medium resolution, and saved into sharded MsgPack files. Uses 24 threads for parallel downloading.

```bash
# Download MP-16 training images (shuffled, medium resolution via Flickr size suffix "z")
python setup/download_images.py \
    --output resources/images/mp16 \
    --url_csv resources/mp16_urls.csv \
    --shuffle \
    --size 320 \
    --size_suffix z \
    --threads 24
```

--------------------------------

### Initialize and Use MsgPackIterableDatasetMultiTargetWithDynLabels

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Initializes a PyTorch IterableDataset for streaming image pairs from MsgPack files with dynamically assigned labels from a JSON mapping. Supports transformations and multi-worker loading.

```python
from dataloader_glimpse import MsgPackIterableDatasetMultiTargetWithDynLabels
import torchvision, torch, json

# Load label mapping
with open("resources/yfcc_25600_places365_mapping_h3.json") as f:
    target_mapping = json.load(f)

# Image transforms for validation
tfm = torchvision.transforms.Compose([
    torchvision.transforms.Resize(256),
    torchvision.transforms.CenterCrop(224),
    torchvision.transforms.ToTensor(),
    torchvision.transforms.Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225)),
])

dataset = MsgPackIterableDatasetMultiTargetWithDynLabels(
    path="resources/images/yfcc25600/yfcc25600_rgb_images/",
    seg_path="resources/images/yfcc25600/yfcc25600_seg_images_PNG/",
    segment_file_path="resources/semantic_cagtegories.mat",
    target_mapping=target_mapping,
    key_img_id="id",
    key_img_encoded="image",
    shuffle=False,
    transformation=tfm,
    transformation_seg=torchvision.transforms.Compose([
        torchvision.transforms.Resize(256),
        torchvision.transforms.ToTensor(),
    ]),
    meta_path="resources/yfcc25600_places365.csv",
    scene_of_interest=3,   # 0=indoor, 1=natural, 2=urban, 3=all
    seg_channels=3,
    percent_seg_pixels=1,
    cache_size=1024,
)

loader = torch.utils.data.DataLoader(dataset, batch_size=128, num_workers=4, pin_memory=True)

# Each batch yields: (rgb_image, seg_image, label_list, lat, lon, scene_key, img_name)
for rgb, seg, labels, lat, lon, scene, img_id in loader:
    print(rgb.shape)    # torch.Size([128, 3, 224, 224])
    print(seg.shape)    # torch.Size([128, 3, 224, 224])
    print(labels)       # list of 3 tensors: [coarse, middle, fine] class labels
    break
```

--------------------------------

### Train ViT Model Script

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Command-line interface for training the ViT model. It supports specifying CUDA device, number of epochs, segmentation channels, scene of interest, and the type of s2 cells. Training uses SGD with MultiStepLR and evaluates top-k accuracy.

```bash
# Train from scratch on GPU 0
python Train_ViT.py \
    --cuda_base cuda:0 \
    --device_ids 0 \
    --epochs 25 \
    --seg_channels 3 \
    --scene_of_interest 3 \
    --s2_cells fine

# Sample training output:
# Epoch [1/25], Step [2000/36285], Loss: 8.4312
# Epoch [1/25], Step [4000/36285], Loss: 7.1089
# Accuracy of the network on the test set after Epoch 1 is: 0.0421
# Top 10 accuracy on the testing: 0.1847
# Top 100 accuracy on the testing: 0.4213
# Top 500 accuracy on the testing: 0.6781
# Best Top_500_accuracy on test set till this epoch: 0.6781 Found in Epoch No: 1
# → checkpoint saved to ./saved_models/Natural_RGB+Seg_Late_Fusion_Multitask_3_scene_ViT_fine.tar
```

--------------------------------

### Download Pre-Trained Model Checkpoint

Source: https://github.com/ewanowara/geolocalization/blob/main/README.md

Downloads the pre-trained Vision Transformer (ViT) model checkpoint. This is required for performing inference with a pre-trained model.

```bash
mkdir -p saved_models
wget https://www.dropbox.com/s/kqi5it6bexhzgmn/Saved_RGB_ViT.tar?dl=0   saved_models/Saved_RGB_ViT.tar
```

--------------------------------

### Write Image Records to MsgPack

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Demonstrates using the `MsgPackWriter` class to write image records (raw JPEG bytes and ID) to sharded MsgPack files. The writer automatically rolls over to a new shard file every `chunk_size` records.

```python
from setup.download_images import MsgPackWriter
import msgpack
from pathlib import Path

output_dir = Path("resources/images/mp16")

with MsgPackWriter(output_dir, chunk_size=4096) as writer:
    # Each record is a dict with raw JPEG bytes and an image id string
    record = {
        "image": open("photo.jpg", "rb").read(),  # raw JPEG bytes
        "id": "flickr_123456789"
    }
    writer.write(record)
# Produces: resources/images/mp16/shard_0.msg, shard_1.msg, ...
```

--------------------------------

### Create DataLoader Instances with MultiPartitioningClassifier

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Instantiates a MultiPartitioningClassifier to wrap dataset configurations from a YAML file, providing `train_dataloader()` and `val_dataloader()` methods for ready-to-use DataLoaders.

```python
from dataloader_glimpse import MultiPartitioningClassifier
from argparse import Namespace
import yaml

with open("config/base_model.yml") as f:
    config = yaml.load(f, Loader=yaml.FullLoader)

model_params = config["model_params"]
classifier = MultiPartitioningClassifier(hparams=Namespace(**model_params))

train_loader = classifier.train_dataloader()
val_loader   = classifier.val_dataloader()

print(f"Batches per train epoch: {len(list(train_loader))}")
```

--------------------------------

### Inference with Pre-Trained Model

Source: https://github.com/ewanowara/geolocalization/blob/main/README.md

Performs geo-localization inference using the downloaded pre-trained model. Specify the GPU to use with `--cuda_base`.

```bash
python Test_ViT.py --cuda_base cuda:0
```

--------------------------------

### Run ViT Model Inference and Report Accuracy

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Loads a saved checkpoint, runs the model in evaluation mode, converts predicted geo-cell indices to coordinates, and reports Great Circle Distance (GCD) accuracy at various thresholds. Ensure the pre-trained checkpoint is downloaded and saved in the 'saved_models' directory.

```bash
# Download pre-trained checkpoint
mkdir -p saved_models
wget "https://www.dropbox.com/s/kqi5it6bexhzgmn/Saved_RGB_ViT.tar?dl=0" \
     -O saved_models/Saved_RGB_ViT.tar

# Run inference
python Test_ViT.py \
    --cuda_base cuda:0 \
    --device_ids 0 \
    --seg_channels 3 \
    --scene_of_interest 3

# Expected output (LaTeX-formatted GCD table row):
# 1 km & 25 km & 200 km & 750 km & 2,500 km \\
# 2.34 & 11.87 & 29.45 & 51.23 & 71.08 \\
# 
# Accuracy of the network on the test set with the saved model is: 0.0832
# Top 10 accuracy on the testing: 0.2341
# Top 100 accuracy on the testing: 0.5127
```

--------------------------------

### Create Coarse Geo-Cell Partitioning

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Creates a geo-cell partitioning using S2 geometry library for the MP-16 dataset. This configuration aims for cells containing 50 to 5000 images, resulting in approximately 3298 cells. Outputs a CSV with cell information.

```bash
# Create coarse partitioning (50–5000 images/cell → ~3298 cells)
python partitioning/create_cells.py \
    --dataset resources/mp16_places365.csv \
    --column_img_path IMG_ID \
    --column_lat LAT \
    --column_lng LON \
    --img_min 50 \
    --img_max 5000 \
    --output resources/s2_cells/
```

--------------------------------

### Create Fine Geo-Cell Partitioning

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Creates a fine-grained geo-cell partitioning for the MP-16 dataset using S2 geometry. This configuration targets cells with 50 to 1000 images, resulting in approximately 12893 cells. The output is a CSV file containing details for each cell.

```bash
# Create fine partitioning (50–1000 images/cell → ~12893 cells)
python partitioning/create_cells.py \
    --dataset resources/mp16_places365.csv \
    --img_min 50 \
    --img_max 1000 \
    --output resources/s2_cells/
```

--------------------------------

### Generate Label Mappings for Train/Val Splits

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Generates JSON label mappings for training and validation splits by computing S2 cells for images based on their latitude and longitude. Outputs mappings used by dataloaders.

```bash
# Generate label mappings for train and val splits
python partitioning/assign_classes.py \
    --config config/base_model.yml \
    --column_img_path IMG_ID \
    --column_lat LAT \
    --column_lng LON

# Output (paths specified in config):
# resources/mp16_places365_mapping_h3.json      ← training labels
# resources/yfcc_25600_places365_mapping_h3.json ← validation labels

# JSON structure example:
# {
#   "flickr_100001.jpg": [2847, 5912, 9103],
#   "flickr_100002.jpg": [1021, 3344, 7821],
#   ...
# }
```

--------------------------------

### Download Flickr Images for Validation

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Downloads YFCC25600 validation images from a CSV of URLs. Images are shuffled, resized to 320 pixels without a size suffix for original resolution, and saved into sharded MsgPack files. Uses 24 threads for parallel downloading.

```bash
# Download YFCC25600 validation images (original resolution, no size suffix)
python setup/download_images.py \
    --output resources/images/yfcc25600 \
    --url_csv resources/yfcc25600_urls.csv \
    --shuffle \
    --size 320 \
    --size_suffix "" \
    --threads 24
```

--------------------------------

### Filter Dataset by Downloaded Images

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Removes entries from JSON label mappings that do not have a corresponding image in the MsgPack dataset. This script ensures consistency between training/validation mappings and the actual downloaded images, preventing KeyErrors during dataloader iteration. Use a configuration file to specify settings.

```bash
# Remove label mapping entries for images that were not downloaded
python setup/filter_by_downloaded_images.py --config config/base_model.yml

# Log output:
# INFO - Expected dataset size: 4654532
# INFO - True dataset size:     4312000
# INFO - Expected dataset size: 25600
# INFO - True dataset size:     24891
```

--------------------------------

### Convert Lat/Lng to S2 Cell and Assign Class Index

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Converts a latitude and longitude pair to an S2 leaf cell and finds the coarsest ancestor cell in a partitioning mapping to retrieve its class label. Requires a pre-loaded partitioning mapping.

```python
import s2sphere as s2
from partitioning.create_cells import create_s2_cell, create_cell_at_level
from partitioning.assign_classes import assign_class_index
import pandas as pd

# Load a partitioning
partitioning = pd.read_csv(
    "resources/s2_cells/cells_50_1000.csv",
    index_col="hex_id",
    skiprows=2,
)
mapping = partitioning["class_label"].to_dict()  # {hex_id -> class_label}

# Convert GPS to S2 cell and look up class label
lat, lng = 48.8566, 2.3522  # Paris, France
cell = create_s2_cell(lat, lng)

class_idx = assign_class_index(cell, mapping)
print(f"Class label for Paris: {class_idx}")
# Class label for Paris: 7821

# Convert back: look up mean coordinates of predicted cell
row = partitioning[partitioning["class_label"] == class_idx].iloc[0]
print(f"Cell center: ({row['latitude_mean']:.4f}, {row['longitude_mean']:.4f})")
# Cell center: (48.8601, 2.3477)
```

--------------------------------

### GeoClassification Dual-Stream ViT Model

Source: https://context7.com/ewanowara/geolocalization/llms.txt

Defines the GeoClassification model, a dual-stream Vision Transformer architecture for geo-spatial classification. It requires PyTorch and Hugging Face Transformers. The model processes RGB and segmentation images separately and fuses their embeddings using a Cross-Modal Attention Fusion head.

```python
import torch
import torch.nn as nn
from transformers import ViTModel, ViTConfig

seg_channels = 3     # 3-channel RGB segmentation map; use 150 for one-hot binary channels
num_classes_fine = 12893
num_scenes = 3

class GeoClassification(nn.Module):
    def __init__(self):
        super().__init__()
        self.vit_RGB = ViTModel(ViTConfig(num_channels=3)).from_pretrained(
            "google/vit-base-patch16-224-in21k"
        )
        self.vit_Seg = ViTModel(ViTConfig(num_channels=seg_channels)).from_pretrained(
            "google/vit-base-patch16-224-in21k"
        )
        hidden = self.vit_RGB.config.hidden_size  # 768
        self.cmaf_1 = nn.Linear(hidden, 8)
        self.cmaf_2 = nn.Linear(8, 1)
        self.dropout = nn.Dropout(p=0.20)
        self.relu = nn.LeakyReLU()
        self.classifier_geo   = nn.Linear(hidden, num_classes_fine)
        self.classifier_scene = nn.Linear(hidden, num_scenes)

    def forward(self, rgb_image, seg_image):
        # seg_image shape from dataloader: (B, H, W, C) → permute to (B, C, H, W)
        seg_image = torch.permute(seg_image, (0, 3, 1, 2))

        cls_rgb = self.vit_RGB(rgb_image).last_hidden_state[:, 0, :]   # (B, 768)
        cls_seg = self.vit_Seg(seg_image).last_hidden_state[:, 0, :]   # (B, 768)

        # CMAF: learn per-stream scalar attention weight
        w_rgb = self.cmaf_2(self.dropout(self.relu(self.cmaf_1(cls_rgb))))  # (B, 1)
        w_seg = self.cmaf_2(self.dropout(self.relu(self.cmaf_1(cls_seg))))  # (B, 1)

        fused = torch.add(cls_rgb * w_rgb, cls_seg * w_seg)          # (B, 768)
        return self.classifier_geo(fused), self.classifier_scene(fused)

# Instantiate and run inference
device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
model = nn.DataParallel(GeoClassification(), device_ids=[0]).to(device)

rgb  = torch.randn(4, 3, 224, 224).to(device)
seg  = torch.randn(4, 224, 224, 3).to(device)   # note HWC layout from dataloader
geo_logits, scene_logits = model(rgb, seg)

print(geo_logits.shape)    # torch.Size([4, 12893])
print(scene_logits.shape)  # torch.Size([4, 3])
```

--------------------------------

### Top-K Classification Accuracy Metric

Source: https://context7.com/ewanowara/geolocalization/llms.txt

A Python function to calculate the top-k accuracy, which is the proportion of samples where the true label is among the top k predicted classes. This is useful for evaluating multi-resolution geo-cell predictions during training.

```python
import numpy as np

def topk_accuracy(target, output, k):
    """
    Args:
        target: 1-D int array of ground-truth class indices, shape (N,)
        output: 2-D float array of class logits/probabilities, shape (N, C)
        k: number of top predictions to consider
    Returns:
        float in [0, 1]
    """
    topn = np.argsort(output, axis=1)[:, -k:]
    return np.mean([1 if target[i] in topn[i] else 0 for i in range(len(topn))])

# Example
N, C = 100, 12893
target = np.random.randint(0, C, size=N)
output = np.random.randn(N, C)

print(f"Top-1  accuracy: {topk_accuracy(target, output, k=1):.4f}")   # ~0.0001
print(f"Top-10 accuracy: {topk_accuracy(target, output, k=10):.4f}")  # ~0.0008
print(f"Top-500 accuracy: {topk_accuracy(target, output, k=500):.4f}") # ~0.0388
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.