fix: DH-21259: Fix maps and add docs

plugins/plotly-express/docs/density-map.md

@@ -0,0 +1,54 @@
+# Density Map
+
+A density map plot is a geographic visualization that connects data points with a heatmap on a geographic map using latitude and longitude coordinates or locations. The heatmap is ideal for visualizing the density of data across geographic areas.
+
+Density map plots are appropriate when the dataset contains geographic coordinates (latitude and longitude) or locations that represent individual points on a map. `density_map` visualizes data using detailed map tiles. For visualizing individual points, use [`scatter_geo`](./scatter-geo.md) or [`scatter_map`](./scatter-map.md).
+
+## What are density map plots useful for?
+
+- **Geographic density**: They are excellent for showing the density of individual geographic locations on a map.
+- **Detailed geographic context**: Density map plots provide a rich and detailed way to visualize geographic data with map tile features.
+
+## Examples
+
+### A basic density map plot
+
+Visualize geographic density by passing longitude and latitude column names to the `lon` and `lat` arguments. Click and drag on the resulting map to pan and zoom.
+
+```python order=density_map_plot,path
+import deephaven.plot.express as dx
+from deephaven import time_table
+
+# Create a simple path dataset
+path = time_table("PT1s").update_view(
+    ["Lon = ((ii - 90) % 360)", "Lat = cos(ii/10) * 30"]
+)
+
+# Create the density map plot
+# Color is set for better visibility
+density_map_plot = dx.density_map(path, lat="Lat", lon="Lon")
+```
+
+### Variable density plot
+
+Provide variable geographic densities by using the `z` argument to specify a column that contains density values.
+
+```python order=density_map_plot,path
+import deephaven.plot.express as dx
+from deephaven import time_table
+
+# Create a simple dataset with density values
+path = time_table("PT1s").update_view(
+    ["Lon = ((ii - 90) % 360)", "Lat = cos(ii/10) * 30", "Z = ii % 100"]
+)
+
+# Create the density map plot
+# Color is set for better visibility
+density_map_plot = dx.density_map(path, lat="Lat", lon="Lon", z="Z")
+```
+
+## API Reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.plot.express.line_map
+```

plugins/plotly-express/docs/line-geo.md

@@ -0,0 +1,51 @@
+# Line Geo
+
+A line geo plot is a geographic visualization that connects data points with lines on a map using latitude and longitude coordinates or locations. The lines are ideal for visualizing relationships between geographic locations such as paths or routes.
+
+Line geo plots are appropriate when the dataset contains geographic coordinates (latitude and longitude) or locations that connect across geographic areas. `line_geo` visualizes data using a basic map projection, without a high degree of detail. For richer tile maps, use [`line_map`](./line-map.md). For visualizing values at individual locations, consider using [`scatter_geo`](./scatter-geo.md).
+
+## What are line geo plots useful for?
+
+- **Geographic relationships**: They are excellent for showing connections or relationships between different geographic locations, such as routes or paths.
+- **Simple geographic context**: Line geo plots provide a clear and straightforward way to visualize geographic data that does not require detailed map features.
+- **Sequential geographic data**: Geographic line plots specialize in showing how data changes across connected geographic points over time or other ordered dimensions.
+
+## Examples
+
+### A basic line geo plot
+
+Visualize geographic paths by passing longitude and latitude column names to the `lon` and `lat` arguments. Click and drag on the resulting map to pan and zoom.
+
+```python order=line_geo_plot,path
+import deephaven.plot.express as dx
+from deephaven import time_table
+
+# Create a simple path dataset
+path = time_table("PT1s").update_view(
+    ["Lon = ((ii - 90) % 360)", "Lat = cos(ii/10) * 30"]
+)
+
+line_geo_plot = dx.line_geo(path, lat="Lat", lon="Lon")
+```
+
+### Color by group
+
+Denote different routes or paths by using the color of the lines as group indicators by passing the grouping column name to the `by` argument.
+
+```python order=line_geo_plot,paths
+import deephaven.plot.express as dx
+from deephaven import time_table
+
+# Create a simple dataset with two paths
+paths = time_table("PT1s").update_view(
+    ["Path = i % 2", "Lon = ((ii - 90) % 360)", "Lat = Path == 0 ? cos(ii/10) * 30 : sin(ii/10) * 30"]
+)
+
+line_geo_colors = dx.line_geo(paths, lat="Lat", lon="Lon", by="Path")
+```
+
+## API Reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.plot.express.line_geo
+```

plugins/plotly-express/docs/line-map.md

@@ -0,0 +1,54 @@
+# Line Map
+
+A line map plot is a geographic visualization that connects data points with lines on a map using latitude and longitude coordinates or locations. The lines are ideal for visualizing relationships between geographic locations such as paths or routes.
+
+Line map plots are appropriate when the dataset contains geographic coordinates (latitude and longitude) or locations that connect across geographic areas. `line_map` visualizes data using detailed map tiles. For simpler projection maps, use [`line_geo`](./line-geo.md). For visualizing values at individual locations, consider using [`scatter_map`](./scatter-map.md).
+
+## What are line map plots useful for?
+
+- **Geographic relationships**: They are excellent for showing connections or relationships between different geographic locations, such as routes or paths.
+- **Detailed geographic context**: Line map plots provide a rich and detailed way to visualize geographic data with map tile features.
+- **Sequential geographic data**: Geographic line plots specialize in showing how data changes across connected geographic points over time or other ordered dimensions.
+
+## Examples
+
+### A basic line map plot
+
+Visualize geographic paths by passing longitude and latitude column names to the `lon` and `lat` arguments. Click and drag on the resulting map to pan and zoom.
+
+```python order=line_map_plot,path
+import deephaven.plot.express as dx
+from deephaven import time_table
+
+# Create a simple path dataset
+path = time_table("PT1s").update_view(
+    ["Lon = ((ii - 90) % 360)", "Lat = cos(ii/10) * 30"]
+)
+
+# Create the line map plot
+# Color is set for better visibility
+line_map_plot = dx.line_map(path, lat="Lat", lon="Lon", color_discrete_sequence="black")
+```
+
+### Color by group
+
+Denote different routes or paths by using the color of the lines as group indicators by passing the grouping column name to the `by` argument.
+
+```python order=line_geo_plot,paths
+import deephaven.plot.express as dx
+from deephaven import time_table
+
+# Create a simple dataset with two paths
+paths = time_table("PT1s").update_view(
+    ["Path = i % 2", "Lon = ((ii - 90) % 360)", "Lat = Path == 0 ? cos(ii/10) * 30 : sin(ii/10) * 30"]
+)
+# Create the line map plot
+# Color is set for better visibility
+line_map_plot = dx.line_map(paths, lat="Lat", lon="Lon", color_discrete_sequence=["black", "darkgrey"], by="Path")
+```
+
+## API Reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.plot.express.line_map
+```

plugins/plotly-express/docs/scatter-geo.md

@@ -0,0 +1,50 @@
+# Scatter Geo
+
+A scatter geo plot is a geographic visualization that displays individual data points on a map using latitude and longitude coordinates or locations. The points are ideal for visualizing the distribution of data across geographic areas.
+
+Scatter geo plots are appropriate when the dataset contains geographic coordinates (latitude and longitude) or locations that represent individual points on a map. `scatter_geo` visualizes data using a basic map projection, without a high degree of detail. For richer tile maps, use [`scatter_map`](./scatter-map.md). For visualizing connections between locations, consider using [`line_geo`](./line-geo.md).
+
+## What are scatter geo plots useful for?
+
+- **Geographic distribution**: They are excellent for showing the distribution of individual geographic locations on a map.
+- **Simple geographic context**: Scatter geo plots provide a clear and straightforward way to visualize geographic data that does not require detailed map features.
+
+## Examples
+
+### A basic scatter geo plot
+
+Visualize geographic paths by passing longitude and latitude column names to the `lon` and `lat` arguments. Click and drag on the resulting map to pan and zoom.
+
+```python order=scatter_geo_plot,path
+import deephaven.plot.express as dx
+from deephaven import time_table
+
+# Create a simple path dataset
+path = time_table("PT1s").update_view(
+    ["Lon = ((ii - 90) % 360)", "Lat = cos(ii/10) * 30"]
+)
+
+scatter_geo_plot = dx.scatter_geo(path, lat="Lat", lon="Lon")
+```
+
+### Color by group
+
+Denote different routes or paths by using the color of the points as group indicators by passing the grouping column name to the `by` argument.
+
+```python order=scatter_geo_plot,paths
+import deephaven.plot.express as dx
+from deephaven import time_table
+
+# Create a simple dataset with two paths
+paths = time_table("PT1s").update_view(
+    ["Path = i % 2", "Lon = ((ii - 90) % 360)", "Lat = Path == 0 ? cos(ii/10) * 30 : sin(ii/10) * 30"]
+)
+
+scatter_geo_colors = dx.scatter_geo(paths, lat="Lat", lon="Lon", by="Path")
+```
+
+## API Reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.plot.express.scatter_geo
+```

plugins/plotly-express/docs/scatter-map.md

@@ -0,0 +1,53 @@
+# Scatter Map
+
+A scatter geo plot is a geographic visualization that displays individual data points on a map using latitude and longitude coordinates or locations. The points are ideal for visualizing the distribution of data across geographic areas.
+
+Scatter map plots are appropriate when the dataset contains geographic coordinates (latitude and longitude) or locations that represent individual points on a map. `scatter_map` visualizes data using detailed map tiles. For simpler projection maps, use [`scatter_geo`](./scatter-geo.md). For visualizing connections between locations, consider using [`line_map`](./line-map.md).
+
+## What are scatter map plots useful for?
+
+- **Geographic distribution**: They are excellent for showing the distribution of individual geographic locations on a map.
+- **Detailed geographic context**: Scatter map plots provide a rich and detailed way to visualize geographic data with map tile features.
+
+## Examples
+
+### A basic scatter map plot
+
+Visualize geographic paths by passing longitude and latitude column names to the `lon` and `lat` arguments. Click and drag on the resulting map to pan and zoom.
+
+```python order=scatter_map_plot,path
+import deephaven.plot.express as dx
+from deephaven import time_table
+
+# Create a simple path dataset
+path = time_table("PT1s").update_view(
+    ["Lon = ((ii - 90) % 360)", "Lat = cos(ii/10) * 30"]
+)
+
+# Create the scatter map plot
+# Color is set for better visibility
+scatter_map_plot = dx.scatter_map(path, lat="Lat", lon="Lon", color_discrete_sequence="black")
+```
+
+### Color by group
+
+Denote different routes or paths by using the color of the lines as group indicators by passing the grouping column name to the `by` argument.
+
+```python order=scatter_map_plot,paths
+import deephaven.plot.express as dx
+from deephaven import time_table
+
+# Create a simple dataset with two paths
+paths = time_table("PT1s").update_view(
+    ["Path = i % 2", "Lon = ((ii - 90) % 360)", "Lat = Path == 0 ? cos(ii/10) * 30 : sin(ii/10) * 30"]
+)
+# Create the scatter map plot
+# Color is set for better visibility
+scatter_map_plot = dx.scatter_map(paths, lat="Lat", lon="Lon", color_discrete_sequence=["black", "darkgrey"], by="Path")
+```
+
+## API Reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.plot.express.scatter_map
+```

plugins/plotly-express/docs/sidebar.json

@@ -33,6 +33,10 @@
             "label": "Density Heatmap",
             "path": "density_heatmap.md"
           },
+          {
+            "label": "Density Map",
+            "path": "density-map.md"
+          },
           {
             "label": "Funnel",
             "path": "funnel.md"
@@ -61,6 +65,14 @@
             "label": "Line 3d",
             "path": "line-3d.md"
           },
+          {
+            "label": "Line Geo",
+            "path": "line-geo.md"
+          },
+          {
+            "label": "Line Map",
+            "path": "line-map.md"
+          },
           {
             "label": "Line Polar",
             "path": "line-polar.md"
@@ -85,6 +97,14 @@
             "label": "Scatter 3d",
             "path": "scatter-3d.md"
           },
+          {
+            "label": "Scatter Geo",
+            "path": "scatter-geo.md"
+          },
+          {
+            "label": "Scatter Map",
+            "path": "scatter-map.md"
+          },
           {
             "label": "Scatter Polar",
             "path": "scatter-polar.md"

plugins/plotly-express/src/deephaven/plot/express/plots/_private_utils.py

@@ -428,6 +428,19 @@ def process_args(
     render_args["args"]["filter_by"] = filter_by
     render_args["args"]["required_filter_by"] = required_filter_by
 
+    if "center" in render_args["args"]:
+        center = render_args["args"].pop("center")
+        if center is None:
+            # Set a default center to prevent px from auto-centering based on data
+            # which breaks the initial view for map plots since the data may be null initially
+            # Auto centering on the server side is also a bad idea since the data can change,
+            # so that should be done on the client side if desired
+            center = {
+                "lat": 0,
+                "lon": 0,
+            }
+        render_args["args"]["center"] = center
+
     orig_process_args = args_copy(render_args)
     orig_process_func = lambda **local_args: create_deephaven_figure(**local_args)[0]
 

plugins/plotly-express/src/deephaven/plot/express/plots/maps.py

@@ -238,7 +238,7 @@ def scatter_map(
     range_color: list[float] | None = None,
     color_continuous_midpoint: float | None = None,
     opacity: float | None = None,
-    zoom: float | None = None,
+    zoom: float | None = 0,
     center: dict[str, float] | None = None,
     map_style: str = "open-street-map",
     title: str | None = None,
@@ -308,7 +308,7 @@ def scatter_map(
       color_continuous_midpoint: A number that is the midpoint of the color axis
       opacity: Opacity to apply to all markers. 0 is completely transparent
         and 1 is completely opaque.
-      zoom: The zoom level of the map.
+      zoom: The zoom level of the map. 0 is the whole world, and higher values zoom in closer.
       center: A dictionary of center coordinates.
         The keys should be 'lat' and 'lon' and the values should be floats
         that represent the lat and lon of the center of the map.
@@ -516,7 +516,7 @@ def line_map(
     size_map: dict[str | tuple[str], str] | None = None,
     width_sequence: list[int] | None = None,
     width_map: dict[str | tuple[str], str] | None = None,
-    zoom: float | None = None,
+    zoom: float | None = 0,
     map_style: str = "open-street-map",
     center: dict[str, float] | None = None,
     title: str | None = None,
@@ -595,7 +595,7 @@ def line_map(
         widths, widths will be reused. This is overriden if "line_dash" is specified.
       line_dash_map: If dict, the keys should be strings of the column values (or a tuple
         of combinations of column values) which map to line_dash.
-      zoom: The zoom level of the map.
+      zoom: The zoom level of the map. 0 is the whole world, and higher values zoom in closer.
       center: A dictionary of center coordinates.
         The keys should be 'lat' and 'lon' and the values should be floats
         that represent the lat and lon of the center of the map.
@@ -633,7 +633,7 @@ def density_map(
     labels: dict[str, str] | None = None,
     radius: int = 30,
     opacity: float | None = None,
-    zoom: float | None = None,
+    zoom: float | None = 0,
     center: dict[str, float] | None = None,
     map_style: str = "open-street-map",
     title: str | None = None,
@@ -656,7 +656,7 @@ def density_map(
       radius: The radius of each point.
       opacity: Opacity to apply to all markers. 0 is completely transparent
         and 1 is completely opaque.
-      zoom: The zoom level of the map.
+      zoom: The zoom level of the map. 0 is the whole world, and higher values zoom in closer.
       center: A dictionary of center coordinates.
         The keys should be 'lat' and 'lon' and the values should be floats
         that represent the lat and lon of the center of the map.