feat: add st_buffer, st_centroid, and st_convexhull and their corresponding GeoSeries methods

GEMINI.md

@@ -0,0 +1,145 @@
+# Contribution guidelines, tailored for LLM agents
+
+## Testing
+
+We use `nox` to instrument our tests.
+
+- To test your changes, run unit tests with `nox`:
+
+  ```bash
+  nox -r -s unit
+  ```
+
+- To run a single unit test:
+
+  ```bash
+  nox -r -s unit-3.13 -- -k <name of test>
+  ```
+
+- To run system tests, you can execute::
+
+   # Run all system tests
+   $ nox -r -s system
+
+   # Run a single system test
+   $ nox -r -s system-3.13 -- -k <name of test>
+
+- The codebase must have better coverage than it had previously after each
+  change. You can test coverage via `nox -s unit system cover` (takes a long
+  time).
+
+## Code Style
+
+- We use the automatic code formatter `black`. You can run it using
+  the nox session `format`. This will eliminate many lint errors. Run via:
+
+  ```bash
+  nox -r -s format
+  ```
+
+- PEP8 compliance is required, with exceptions defined in the linter configuration.
+  If you have ``nox`` installed, you can test that you have not introduced
+  any non-compliant code via:
+
+  ```
+  nox -r -s lint
+  ```
+
+## Documentation
+
+If a method or property is implementing the same interface as a third-party
+package such as pandas or scikit-learn, place the relevant docstring in the
+corresponding `third_party/bigframes_vendored/package_name` directory, not in
+the `bigframes` directory. Implementations may be placed in the `bigframes`
+directory, though.
+
+### Testing code samples
+
+Code samples are very important for accurate documentation. We use the "doctest"
+framework to ensure the samples are functioning as expected. After adding a code
+sample, please ensure it is correct by running doctest. To run the samples
+doctests for just a single method, refer to the following example:
+
+```bash
+pytest --doctest-modules bigframes/pandas/__init__.py::bigframes.pandas.cut
+```
+
+## Tips for implementing common BigFrames features
+
+### Adding a scalar operator
+
+For an example, see commit
+[c5b7fdae74a22e581f7705bc0cf5390e928f4425](https://github.com/googleapis/python-bigquery-dataframes/commit/c5b7fdae74a22e581f7705bc0cf5390e928f4425).
+
+To add a new scalar operator, follow these steps:
+
+1.  **Define the operation dataclass:**
+    - In `bigframes/operations/`, find the relevant file (e.g., `geo_ops.py` for geography functions) or create a new one.
+    - Create a new dataclass inheriting from `base_ops.UnaryOp` for unary
+      operators, `base_ops.BinaryOp` for binary operators, `base_ops.TernaryOp`
+      for ternary operators, or `base_ops.NaryOp for operators with many
+      arguments. Note that these operators are counting the number column-like
+      arguments. A function that takes only a single column but several literal
+      values would still be a `UnaryOp`.
+    - Define the `name` of the operation and any parameters it requires.
+    - Implement the `output_type` method to specify the data type of the result.
+
+2.  **Export the new operation:**
+    - In `bigframes/operations/__init__.py`, import your new operation dataclass and add it to the `__all__` list.
+
+3.  **Implement the user-facing function (pandas-like):**
+
+    - Identify the canonical function from pandas / geopandas / awkward array /
+      other popular Python package that this operator implements.
+    - Find the corresponding class in BigFrames. For example, the implementation
+      for most geopandas.GeoSeries methods is in
+      `bigframes/geopandas/geoseries.py`. Pandas Series methods are implemented
+      in `bigframes/series.py` or one of the accessors, such as `StringMethods`
+      in `bigframes/operations/strings.py`.
+    - Create the user-facing function that will be called by users (e.g., `length`).
+    - If the SQL method differs from pandas or geopandas in a way that can't be
+      made the same, raise a `NotImplementedError` with an appropriate message and
+      link to the feedback form.
+    - Add the docstring to the corresponding file in
+      `third_party/bigframes_vendored`, modeled after pandas / geopandas.
+
+4.  **Implement the user-facing function (SQL-like):**
+
+    - In `bigframes/bigquery/_operations/`, find the relevant file (e.g., `geo.py`) or create a new one.
+    - Create the user-facing function that will be called by users (e.g., `st_length`).
+    - This function should take a `Series` for any column-like inputs, plus any other parameters.
+    - Inside the function, call `series._apply_unary_op`,
+      `series._apply_binary_op`, or similar passing the operation dataclass you
+      created.
+    - Add a comprehensive docstring with examples.
+    - In `bigframes/bigquery/__init__.py`, import your new user-facing function and add it to the `__all__` list.
+
+5.  **Implement the compilation logic:**
+    - In `bigframes/core/compile/scalar_op_compiler.py`:
+        - If the BigQuery function has a direct equivalent in Ibis, you can often reuse an existing Ibis method.
+        - If not, define a new Ibis UDF using `@ibis_udf.scalar.builtin` to map to the specific BigQuery function signature.
+        - Create a new compiler implementation function (e.g., `geo_length_op_impl`).
+        - Register this function to your operation dataclass using `@scalar_op_compiler.register_unary_op` or `@scalar_op_compiler.register_binary_op`.
+        - This implementation will translate the BigQuery DataFrames operation into the appropriate Ibis expression.
+
+6.  **Add Tests:**
+    - Add system tests in the `tests/system/` directory to verify the end-to-end
+      functionality of the new operator. Test various inputs, including edge cases
+      and `NULL` values.
+
+      Where possible, run the same test code against pandas or GeoPandas and
+      compare that the outputs are the same (except for dtypes if BigFrames
+      differs from pandas).
+    - If you are overriding a pandas or GeoPandas property, add a unit test to
+      ensure the correct behavior (e.g., raising `NotImplementedError` if the
+      functionality is not supported).
+
+
+## Constraints
+
+- Only add git commits. Do not change git history.
+- Follow the spec file for development.
+  - Check off items in the "Acceptance
+    criteria" and "Detailed steps" sections with `[x]`.
+  - Please do this as they are completed.
+  - Refer back to the spec after each step.

bigframes/bigquery/__init__.py

@@ -29,6 +29,9 @@
 )
 from bigframes.bigquery._operations.geo import (
     st_area,
+    st_buffer,
+    st_centroid,
+    st_convexhull,
     st_difference,
     st_distance,
     st_intersection,
@@ -54,11 +57,18 @@
     # approximate aggregate ops
     "approx_top_count",
     # array ops
-    "array_length",
     "array_agg",
+    "array_length",
     "array_to_string",
+    # datetime ops
+    "unix_micros",
+    "unix_millis",
+    "unix_seconds",
     # geo ops
     "st_area",
+    "st_buffer",
+    "st_centroid",
+    "st_convexhull",
     "st_difference",
     "st_distance",
     "st_intersection",
@@ -81,8 +91,4 @@
     "sql_scalar",
     # struct ops
     "struct",
-    # datetime ops
-    "unix_micros",
-    "unix_millis",
-    "unix_seconds",
 ]

bigframes/bigquery/_operations/geo.py

@@ -103,6 +103,198 @@ def st_area(
     return series
 
 
+def st_buffer(
+    series: Union[bigframes.series.Series, bigframes.geopandas.GeoSeries],
+    buffer_radius: float,
+    num_seg_quarter_circle: float = 8.0,
+    use_spheroid: bool = False,
+    endcap: str = "ROUND",
+    side: str = "BOTH",
+) -> bigframes.series.Series:
+    """
+    Computes a `GEOGRAPHY` that represents all points whose distance from the
+    input `GEOGRAPHY` is less than or equal to `distance` meters.
+
+    .. note::
+        BigQuery's Geography functions, like `st_buffer`, interpret the geometry
+        data type as a point set on the Earth's surface. A point set is a set
+        of points, lines, and polygons on the WGS84 reference spheroid, with
+        geodesic edges. See: https://cloud.google.com/bigquery/docs/geospatial-data
+
+    **Examples:**
+
+        >>> import bigframes.geopandas
+        >>> import bigframes.pandas as bpd
+        >>> import bigframes.bigquery as bbq
+        >>> from shapely.geometry import Point
+        >>> bpd.options.display.progress_bar = None
+
+        >>> series = bigframes.geopandas.GeoSeries(
+        ...         [
+        ...             Point(0, 0),
+        ...             Point(1, 1),
+        ...         ]
+        ... )
+        >>> series
+        0    POINT (0 0)
+        1    POINT (1 1)
+        dtype: geometry
+
+        >>> bbq.st_buffer(series, 1000)
+        0    POLYGON ((-0.00899 0.00005, -0.00883 -0.00171,...
+        1    POLYGON ((0.99101 1.00005, 0.99117 0.99829, 0....
+        dtype: geometry
+
+    Args:
+        series (bigframes.pandas.Series | bigframes.geopandas.GeoSeries):
+            A series containing geography objects.
+        buffer_radius (float):
+            The distance in meters.
+        num_seg_quarter_circle (float, optional):
+            Specifies the number of segments that are used to approximate a
+            quarter circle. The default value is 8.0.
+        use_spheroid (bool, optional):
+            Determines how this function measures distance. If use_spheroid is
+            FALSE, the function measures distance on the surface of a perfect
+            sphere. The use_spheroid parameter currently only supports the
+            value FALSE. The default value of use_spheroid is FALSE.
+        endcap (str, optional):
+            Allows you to specify one of two endcap styles: ROUND and FLAT.
+            The default value is ROUND. This option only affects the endcaps
+            of buffered linestrings.
+        side (str, optional):
+            Allows you to specify one of three possibilities for lines: BOTH,
+            LEFT, and RIGHT. The default is BOTH. This option only affects
+            how linestrings are buffered.
+
+    Returns:
+      bigframes.pandas.Series:
+          A series of geography objects representing the buffered geometries.
+    """
+    op = ops.GeoStBufferOp(
+        buffer_radius=buffer_radius,
+        num_seg_quarter_circle=num_seg_quarter_circle,
+        use_spheroid=use_spheroid,
+        endcap=endcap,
+        side=side,
+    )
+    series = series._apply_unary_op(op)
+    series.name = None
+    return series
+
+
+def st_centroid(
+    series: Union[bigframes.series.Series, bigframes.geopandas.GeoSeries],
+) -> bigframes.series.Series:
+    """
+    Computes the geometric centroid of a `GEOGRAPHY` type.
+
+    For `POINT` and `MULTIPOINT` types, this is the arithmetic mean of the
+    input coordinates. For `LINESTRING` and `POLYGON` types, this is the
+    center of mass. For `GEOMETRYCOLLECTION` types, this is the center of
+    mass of the collection's elements.
+
+    .. note::
+        BigQuery's Geography functions, like `st_centroid`, interpret the geometry
+        data type as a point set on the Earth's surface. A point set is a set
+        of points, lines, and polygons on the WGS84 reference spheroid, with
+        geodesic edges. See: https://cloud.google.com/bigquery/docs/geospatial-data
+
+    **Examples:**
+
+        >>> import bigframes.geopandas
+        >>> import bigframes.pandas as bpd
+        >>> import bigframes.bigquery as bbq
+        >>> from shapely.geometry import Polygon, LineString, Point
+        >>> bpd.options.display.progress_bar = None
+
+        >>> series = bigframes.geopandas.GeoSeries(
+        ...         [
+        ...             Polygon([(0.0, 0.0), (0.1, 0.1), (0.0, 0.1)]),
+        ...             LineString([(0, 0), (1, 1), (0, 1)]),
+        ...             Point(0, 1),
+        ...         ]
+        ... )
+        >>> series
+        0              POLYGON ((0 0, 0.1 0.1, 0 0.1, 0 0))
+        1                        LINESTRING (0 0, 1 1, 0 1)
+        2                                       POINT (0 1)
+        dtype: geometry
+
+        >>> bbq.st_centroid(series)
+        0    POINT (0.03333 0.06667)
+        1    POINT (0.49998 0.70712)
+        2                  POINT (0 1)
+        dtype: geometry
+
+    Args:
+        series (bigframes.pandas.Series | bigframes.geopandas.GeoSeries):
+            A series containing geography objects.
+
+    Returns:
+      bigframes.pandas.Series:
+          A series of geography objects representing the centroids.
+    """
+    series = series._apply_unary_op(ops.geo_st_centroid_op)
+    series.name = None
+    return series
+
+
+def st_convexhull(
+    series: Union[bigframes.series.Series, bigframes.geopandas.GeoSeries],
+) -> bigframes.series.Series:
+    """
+    Computes the convex hull of a `GEOGRAPHY` type.
+
+    The convex hull is the smallest convex set that contains all of the
+    points in the input `GEOGRAPHY`.
+
+    .. note::
+        BigQuery's Geography functions, like `st_convexhull`, interpret the geometry
+        data type as a point set on the Earth's surface. A point set is a set
+        of points, lines, and polygons on the WGS84 reference spheroid, with
+        geodesic edges. See: https://cloud.google.com/bigquery/docs/geospatial-data
+
+    **Examples:**
+
+        >>> import bigframes.geopandas
+        >>> import bigframes.pandas as bpd
+        >>> import bigframes.bigquery as bbq
+        >>> from shapely.geometry import Polygon, LineString, Point
+        >>> bpd.options.display.progress_bar = None
+
+        >>> series = bigframes.geopandas.GeoSeries(
+        ...         [
+        ...             Polygon([(0.0, 0.0), (0.1, 0.1), (0.0, 0.1)]),
+        ...             LineString([(0, 0), (1, 1), (0, 1)]),
+        ...             Point(0, 1),
+        ...         ]
+        ... )
+        >>> series
+        0              POLYGON ((0 0, 0.1 0.1, 0 0.1, 0 0))
+        1                        LINESTRING (0 0, 1 1, 0 1)
+        2                                       POINT (0 1)
+        dtype: geometry
+
+        >>> bbq.st_convexhull(series)
+        0    POLYGON ((0 0, 0.1 0.1, 0 0.1, 0 0))
+        1          POLYGON ((0 0, 1 1, 0 1, 0 0))
+        2                                POINT (0 1)
+        dtype: geometry
+
+    Args:
+        series (bigframes.pandas.Series | bigframes.geopandas.GeoSeries):
+            A series containing geography objects.
+
+    Returns:
+      bigframes.pandas.Series:
+          A series of geography objects representing the convex hulls.
+    """
+    series = series._apply_unary_op(ops.geo_st_convexhull_op)
+    series.name = None
+    return series
+
+
 def st_difference(
     series: Union[bigframes.series.Series, bigframes.geopandas.GeoSeries],
     other: Union[