Skip to content

map_tools module

MapSession

Manages a leafmap session with map instance.

Source code in geoai/agents/map_tools.py 
 7
 8
 9
10
11
12
13
14
15
16
17
class MapSession:
    """Manages a leafmap session with map instance."""

    def __init__(self, m: Optional[leafmap.Map] = None) -> None:
        """Initialize map session.

        Args:
            m: Optional existing map instance. If None, creates a default map.
        """
        # allow user to pass a map, otherwise create a default
        self.m: leafmap.Map = m or leafmap.Map(style="liberty", projection="globe")

__init__(m=None)

Initialize map session.

Parameters:

Name Type Description Default
m Optional[Map]

Optional existing map instance. If None, creates a default map.

 None
Source code in geoai/agents/map_tools.py 
10
11
12
13
14
15
16
17
def __init__(self, m: Optional[leafmap.Map] = None) -> None:
    """Initialize map session.

    Args:
        m: Optional existing map instance. If None, creates a default map.
    """
    # allow user to pass a map, otherwise create a default
    self.m: leafmap.Map = m or leafmap.Map(style="liberty", projection="globe")

MapTools

Collection of tools for interacting with leafmap instances.

Source code in geoai/agents/map_tools.py 
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
class MapTools:
    """Collection of tools for interacting with leafmap instances."""

    def __init__(self, session: Optional[MapSession] = None) -> None:
        """Initialize map tools.

        Args:
            session: Optional MapSession instance. If None, creates a default session.
        """
        self.session: MapSession = session or MapSession()

    @tool(
        description="Create or reset a Leafmap map with optional center/zoom and basemap."
    )
    def create_map(
        self,
        center_lat: float = 20.0,
        center_lon: float = 0.0,
        zoom: int = 2,
        style: str = "liberty",
        projection: str = "globe",
        use_message_queue: bool = True,
    ) -> str:
        """Create or reset a Leafmap map with specified parameters.

        Args:
            center_lat: Latitude for map center (default: 20.0).
            center_lon: Longitude for map center (default: 0.0).
            zoom: Initial zoom level (default: 2).
            style: Map style name (default: "liberty").
            projection: Map projection (default: "globe").
            use_message_queue: Whether to use message queue (default: True).

        Returns:
            Confirmation message.
        """
        self.session.m = leafmap.Map(
            center=[center_lon, center_lat],
            zoom=zoom,
            style=style,
            projection=projection,
            use_message_queue=use_message_queue,
        )
        self.session.m.create_container()
        return "Map created."

    @tool(description="Add a basemap by name")
    def add_basemap(self, name: str) -> str:
        """Add a basemap to the map by name.

        Args:
            name: Name of the basemap to add.

        Returns:
            Confirmation message with basemap name.
        """
        self.session.m.add_basemap(name)
        return f"Basemap added: {name}"

    @tool(description="Add a vector dataset (GeoJSON, Shapefile, etc.)")
    def add_vector(self, data: str, name: Optional[str] = None) -> str:
        """Add a vector dataset to the map.

        Args:
            data: Path or URL to the vector data file.
            name: Optional name for the layer.

        Returns:
            Confirmation message with layer name.
        """
        self.session.m.add_vector(data=data, name=name)
        return f"Vector added: {name}"

    @tool(description="Fly to a specific location")
    def fly_to(self, longitude: float, latitude: float, zoom: int = 12) -> str:
        """Fly to a specific geographic location.

        Args:
            longitude: Target longitude coordinate.
            latitude: Target latitude coordinate.
            zoom: Zoom level for the target location (default: 12).

        Returns:
            Confirmation message with coordinates and zoom level.
        """
        self.session.m.fly_to(longitude, latitude, zoom)
        return f"Flown to: {longitude}, {latitude}, zoom {zoom}"

    @tool(description="Add Cloud Optimized GeoTIFF (COG) to the map")
    def add_cog_layer(
        self,
        url: str,
        name: Optional[str] = None,
        attribution: str = "TiTiler",
        opacity: float = 1.0,
        visible: bool = True,
        bands: Optional[List[int]] = None,
        nodata: Optional[Union[int, float]] = 0,
        titiler_endpoint: str = "https://titiler.xyz",
    ) -> str:
        """Add a Cloud Optimized GeoTIFF (COG) layer to the map.

        Args:
            url: URL to the COG file.
            name: Optional name for the layer.
            attribution: Attribution text (default: "TiTiler").
            opacity: Layer opacity from 0.0 to 1.0 (default: 1.0).
            visible: Whether the layer is initially visible (default: True).
            bands: Optional list of band indices to display.
            nodata: No data value (default: 0).
            titiler_endpoint: TiTiler endpoint URL (default: "https://titiler.xyz").

        Returns:
            Confirmation message with COG URL.
        """
        self.session.m.add_cog_layer(
            url, name, attribution, opacity, visible, bands, nodata, titiler_endpoint
        )
        return f"COG layer added: {url}"

    @tool(description="Remove a layer by name")
    def remove_layer(self, name: str) -> str:
        """Remove a layer from the map by name.

        Args:
            name: Name of the layer to remove.

        Returns:
            Confirmation message with removed layer name.
        """
        self.session.m.remove_layer(name)
        return f"Removed: {name}"

__init__(session=None)

Initialize map tools.

Parameters:

Name Type Description Default
session Optional[MapSession]

Optional MapSession instance. If None, creates a default session.

 None
Source code in geoai/agents/map_tools.py 
23
24
25
26
27
28
29
def __init__(self, session: Optional[MapSession] = None) -> None:
    """Initialize map tools.

    Args:
        session: Optional MapSession instance. If None, creates a default session.
    """
    self.session: MapSession = session or MapSession()

add_basemap(name)

Add a basemap to the map by name.

Parameters:

Name Type Description Default
name str

Name of the basemap to add.

 required

Returns:

Type Description
str

Confirmation message with basemap name.
Source code in geoai/agents/map_tools.py 
66
67
68
69
70
71
72
73
74
75
76
77
@tool(description="Add a basemap by name")
def add_basemap(self, name: str) -> str:
    """Add a basemap to the map by name.

    Args:
        name: Name of the basemap to add.

    Returns:
        Confirmation message with basemap name.
    """
    self.session.m.add_basemap(name)
    return f"Basemap added: {name}"

add_cog_layer(url, name=None, attribution='TiTiler', opacity=1.0, visible=True, bands=None, nodata=0, titiler_endpoint='https://titiler.xyz')

Add a Cloud Optimized GeoTIFF (COG) layer to the map.

Parameters:

Name Type Description Default
url str

URL to the COG file.

 required
name Optional[str]

Optional name for the layer.

 None
attribution str

Attribution text (default: "TiTiler").

 'TiTiler'
opacity float

Layer opacity from 0.0 to 1.0 (default: 1.0).

 1.0
visible bool

Whether the layer is initially visible (default: True).

 True
bands Optional[List[int]]

Optional list of band indices to display.

 None
nodata Optional[Union[int, float]]

No data value (default: 0).

 0
titiler_endpoint str

TiTiler endpoint URL (default: "https://titiler.xyz").

 'https://titiler.xyz'

Returns:

Type Description
str

Confirmation message with COG URL.
Source code in geoai/agents/map_tools.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
@tool(description="Add Cloud Optimized GeoTIFF (COG) to the map")
def add_cog_layer(
    self,
    url: str,
    name: Optional[str] = None,
    attribution: str = "TiTiler",
    opacity: float = 1.0,
    visible: bool = True,
    bands: Optional[List[int]] = None,
    nodata: Optional[Union[int, float]] = 0,
    titiler_endpoint: str = "https://titiler.xyz",
) -> str:
    """Add a Cloud Optimized GeoTIFF (COG) layer to the map.

    Args:
        url: URL to the COG file.
        name: Optional name for the layer.
        attribution: Attribution text (default: "TiTiler").
        opacity: Layer opacity from 0.0 to 1.0 (default: 1.0).
        visible: Whether the layer is initially visible (default: True).
        bands: Optional list of band indices to display.
        nodata: No data value (default: 0).
        titiler_endpoint: TiTiler endpoint URL (default: "https://titiler.xyz").

    Returns:
        Confirmation message with COG URL.
    """
    self.session.m.add_cog_layer(
        url, name, attribution, opacity, visible, bands, nodata, titiler_endpoint
    )
    return f"COG layer added: {url}"

add_vector(data, name=None)

Add a vector dataset to the map.

Parameters:

Name Type Description Default
data str

Path or URL to the vector data file.

 required
name Optional[str]

Optional name for the layer.

 None

Returns:

Type Description
str

Confirmation message with layer name.
Source code in geoai/agents/map_tools.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
@tool(description="Add a vector dataset (GeoJSON, Shapefile, etc.)")
def add_vector(self, data: str, name: Optional[str] = None) -> str:
    """Add a vector dataset to the map.

    Args:
        data: Path or URL to the vector data file.
        name: Optional name for the layer.

    Returns:
        Confirmation message with layer name.
    """
    self.session.m.add_vector(data=data, name=name)
    return f"Vector added: {name}"

create_map(center_lat=20.0, center_lon=0.0, zoom=2, style='liberty', projection='globe', use_message_queue=True)

Create or reset a Leafmap map with specified parameters.

Parameters:

Name Type Description Default
center_lat float

Latitude for map center (default: 20.0).

 20.0
center_lon float

Longitude for map center (default: 0.0).

 0.0
zoom int

Initial zoom level (default: 2).

 2
style str

Map style name (default: "liberty").

 'liberty'
projection str

Map projection (default: "globe").

 'globe'
use_message_queue bool

Whether to use message queue (default: True).

 True

Returns:

Type Description
str

Confirmation message.
Source code in geoai/agents/map_tools.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
@tool(
    description="Create or reset a Leafmap map with optional center/zoom and basemap."
)
def create_map(
    self,
    center_lat: float = 20.0,
    center_lon: float = 0.0,
    zoom: int = 2,
    style: str = "liberty",
    projection: str = "globe",
    use_message_queue: bool = True,
) -> str:
    """Create or reset a Leafmap map with specified parameters.

    Args:
        center_lat: Latitude for map center (default: 20.0).
        center_lon: Longitude for map center (default: 0.0).
        zoom: Initial zoom level (default: 2).
        style: Map style name (default: "liberty").
        projection: Map projection (default: "globe").
        use_message_queue: Whether to use message queue (default: True).

    Returns:
        Confirmation message.
    """
    self.session.m = leafmap.Map(
        center=[center_lon, center_lat],
        zoom=zoom,
        style=style,
        projection=projection,
        use_message_queue=use_message_queue,
    )
    self.session.m.create_container()
    return "Map created."

fly_to(longitude, latitude, zoom=12)

Fly to a specific geographic location.

Parameters:

Name Type Description Default
longitude float

Target longitude coordinate.

 required
latitude float

Target latitude coordinate.

 required
zoom int

Zoom level for the target location (default: 12).

 12

Returns:

Type Description
str

Confirmation message with coordinates and zoom level.
Source code in geoai/agents/map_tools.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
@tool(description="Fly to a specific location")
def fly_to(self, longitude: float, latitude: float, zoom: int = 12) -> str:
    """Fly to a specific geographic location.

    Args:
        longitude: Target longitude coordinate.
        latitude: Target latitude coordinate.
        zoom: Zoom level for the target location (default: 12).

    Returns:
        Confirmation message with coordinates and zoom level.
    """
    self.session.m.fly_to(longitude, latitude, zoom)
    return f"Flown to: {longitude}, {latitude}, zoom {zoom}"

remove_layer(name)

Remove a layer from the map by name.

Parameters:

Name Type Description Default
name str

Name of the layer to remove.

 required

Returns:

Type Description
str

Confirmation message with removed layer name.
Source code in geoai/agents/map_tools.py 
140
141
142
143
144
145
146
147
148
149
150
151
@tool(description="Remove a layer by name")
def remove_layer(self, name: str) -> str:
    """Remove a layer from the map by name.

    Args:
        name: Name of the layer to remove.

    Returns:
        Confirmation message with removed layer name.
    """
    self.session.m.remove_layer(name)
    return f"Removed: {name}"