Issues using the GTI prefix with TileClient

[kisa72]

Hi,
I have created a spatiotemporal Index stored inside a SQLite/GeoPackage container to hold a very large collection of Hillshade COG files (potentially up to 1000000 files).
I have also created a .gpkg table to improve the efficiancy of readong all the COG files (GDAL Tile Index (GTI).
My wish is to use Streamlit/Leafmap to view and zoom in and out fo the the COG images.

I'm running into a wall I can't get past is what appears to be an incorrect scheme parsing of GDAL driver prefixes, specifically the GTI prefix.

I am a hobbiest python coder and to be honest I'm way out of my depth to the point I am using AI to help complete this task, but have spent days going around in circles trying to resolve this issue with multiple attempts to fool the system to make it work. I am working in windows, but even moved into WSL in hope it may have been a Windows created issue, but still to no avail.

Here is an overview from teh AI as to what we're trying to and what it believes is causing he issue:-

Here is exactly what is happening under the hood:
GDAL's "Driver Prefix" Syntax: GDAL uses a prefix followed by a colon (like GTI:, VRT:, or COG:) to tell the engine which driver to use for a specific file.
localtileserver URL Detection: When you pass a string to TileClient(source), the library tries to be helpful by guessing if it’s a local file path or a remote URL.
The Mistake: Because the library sees a colon (:), it assumes the string is a URL. It thinks GTI is the protocol (like http).
The Crash: In a standard URL, the protocol is followed by :// (two slashes), which is then followed by the Authority (the server address). Because your path only has one slash (GTI:/mnt/...), the internal URL parser fails to find a server name. It returns a None object for the "Authority," and the code crashes when it tries to do anything with that None object.
The Error Message: AttributeError: 'NoneType' object has no attribute 'to_authority' is the "smoking gun." It proves the library is trying to treat a local driver path as a network URL..

Issue: TileClient crashes with AttributeError when using GDAL driver prefixes (like GTI:).
Description: I am trying to use the GDAL Raster Tile Index (GTI) driver to efficiently serve a large mosaic (1,000,000+ COGs) from a GeoPackage.
When I pass the connection string GTI:/absolute/path/to/index.gpkg to TileClient, the library appears to misidentify the GTI: prefix as a URL scheme. This triggers a NoneType error during URL normalization because the parser is looking for a server authority that doesn't exist in a local driver path.
Traceback Highlight: AttributeError: 'NoneType' object has no attribute 'to_authority'
Request: Could TileClient be updated to recognize common GDAL driver prefixes as local file paths instead of attempting to parse them as remote URLs?

Here is a code example:-

import os
from localtileserver import TileClient

# 1. Create a dummy file so the library sees a valid path on disk
dummy_file = "test_index.gpkg"
with open(dummy_file, "w") as f:
    f.write("dummy data")

# 2. Construct the GTI connection string
# This is valid GDAL syntax, but it triggers the localtileserver URL parser
path = os.path.abspath(dummy_file)
gti_path = f"GTI:{path}"

print(f"Testing path: {gti_path}")

try:
    # This is where the AttributeError: 'NoneType' object has no attribute 'to_authority' occurs
    client = TileClient(gti_path)
    print("Success!")
except Exception as e:
    print(f"\nCaught Expected Error: {e}")
    import traceback
    traceback.print_exc()

# Cleanup
if os.path.exists(dummy_file):
    os.remove(dummy_file)

Issue Recap
Title: AttributeError when using GDAL Driver Prefixes (GTI, VRT, etc.) in WSL/Linux
Body:
I am working on a project involving a massive collection of COGs (1M+) and I'm utilizing the GDAL Tile Index (GTI) driver for efficient serving.
The Problem:
When passing a GDAL connection string (e.g., GTI:/path/to/file.gpkg) to TileClient, the library appears to misinterpret the driver prefix as a URL scheme (like http). Because the string doesn't follow the scheme://authority/path format, the internal URI normalization fails.
Environment:
OS: WSL2 (Ubuntu 22.04)
localtileserver version: [Insert your version, e.g., 0.6.4]
Error Traceback:
AttributeError: 'NoneType' object has no attribute 'to_authority'
This seems to happen because the parser returns None for the authority/host when it encounters a single slash after the colon, which then crashes the to_authority call in the library's path cleaning logic.
Proposed Fix:
Could the TileClient path validation be updated to ignore or bypass URL normalization if the string starts with known GDAL prefixes like GTI:, VRT:, or COG:?

Any help would be greatly appreciated.
Thank you.
Markus

[banesullivan]

Ah! Interesting use case! Indeed, I have a feeling that some of the internal logic to localtileserver is failing to handle the GTI prefix and pass that along to the underlying GDAL driver.

Could you point me to an example dataset that I could use to test and validate this? Ideally, I'd like to support this use case but I'll need a simple dataset to write tests against

[kisa72]

Any thoughts?

[banesullivan]

Hey, sorry I haven't had a chance to get back to this yet... I'll try to either tonight or in the next couple of days

[kisa72]

All good, thank you. When ever you have time and are interested is perfectly fine. If it's something that may take you weeks to do (which is fine), just let me know and I'll investigate if there's other ways to do it.

[banesullivan]

Hey @kisa72 , thanks for the detailed write-up and for sharing the data. That made this much easier to dig into.

Good news: the full stack (GDAL, rasterio, rio-tiler) already supports GTI natively. The only issue is in localtileserver's path parsing. Your diagnosis is spot on. urlparse sees GTI: and treats it as a URL scheme. Since it doesn't match http/https/s3, it falls through to pathlib.Path(), which prepends the working directory and produces a garbage path.

I'm working on a fix for this now.

In the meantime, you actually have a workaround available today. Your file already has the .gti.gpkg extension, which GDAL auto-detects as a GTI source. You can skip the GTI: prefix entirely and pass the path directly:

client = TileClient("/path/to/australia_hillshade_index.gti.gpkg")

I confirmed this works with your sample data. No code changes needed on your end.

The proper fix will add support for GTI: and other GDAL driver prefixes so both forms work. I'll follow up here when the PR is ready.

[banesullivan]

#247 adds support for this. I'll issue a new release shortly