.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/14_surface_encoding.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_14_surface_encoding.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_14_surface_encoding.py:


Surface Encoding (2.5D Elevation)
=================================

This example demonstrates end-to-end surface-based encoding:

1. Build a regular block model from geometry.
2. Create a raster-backed elevation surface.
3. Evaluate a fraction-below-surface value for all block centroids.
4. Persist the result as a block-model attribute.
5. Visualise the resulting fractions in 3D.

.. GENERATED FROM PYTHON SOURCE LINES 13-24

.. code-block:: Python


    import tempfile
    from pathlib import Path

    import numpy as np
    import pandas as pd
    import matplotlib.pyplot as plt

    from parq_blockmodel import ParquetBlockModel, RasterSurface, RegularGeometry









.. GENERATED FROM PYTHON SOURCE LINES 25-27

Create a geometry-backed block model
------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 27-41

.. code-block:: Python


    temp_dir = Path(tempfile.gettempdir()) / "surface_encoding_example"
    temp_dir.mkdir(parents=True, exist_ok=True)
    pbm_path = temp_dir / "surface_encoding.pbm"

    geometry = RegularGeometry(
        corner=(0.0, 0.0, 0.0),
        block_size=(1.0, 1.0, 1.0),
        shape=(20, 16, 6),
    )
    pbm = ParquetBlockModel.from_geometry(geometry=geometry, path=pbm_path)
    blocks = pbm.read(index=None)









.. GENERATED FROM PYTHON SOURCE LINES 42-44

Build and ingest a raster surface
---------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 44-54

.. code-block:: Python


    x_coords = np.linspace(-0.5, 19.5, 9)
    y_coords = np.linspace(-0.5, 15.5, 7)
    xx, yy = np.meshgrid(x_coords, y_coords, indexing="xy")
    values = 3.5 + 0.08 * xx - 0.04 * yy
    surface = RasterSurface.from_arrays(x_coords=x_coords, y_coords=y_coords, values=values, name="topography")

    print("Surface name:", surface.name)






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Surface name: topography




.. GENERATED FROM PYTHON SOURCE LINES 55-57

Evaluate the surface and visualise in 3D
----------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 57-81

.. code-block:: Python


    values = pbm.evaluate_surface(surface, column="topo_fraction")
    block_ids = blocks["block_id"].to_numpy(dtype=np.int64)
    blocks["topo_fraction"] = values[block_ids]

    fig = plt.figure(figsize=(9, 6))
    ax = fig.add_subplot(111, projection="3d")
    scatter = ax.scatter(
        blocks["x"],
        blocks["y"],
        blocks["z"],
        c=blocks["topo_fraction"],
        cmap="viridis",
        s=18,
        edgecolors="none",
    )
    ax.set_title("Surface fraction below topography")
    ax.set_xlabel("X")
    ax.set_ylabel("Y")
    ax.set_zlabel("Z")
    fig.colorbar(scatter, ax=ax, label="Fraction below surface", shrink=0.75)
    plt.show()





.. image-sg:: /auto_examples/images/sphx_glr_14_surface_encoding_001.png
   :alt: Surface fraction below topography
   :srcset: /auto_examples/images/sphx_glr_14_surface_encoding_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 82-84

.. code-block:: Python

    print("topo_fraction:")
    print(pbm.read(columns=["topo_fraction"], index=None)["topo_fraction"].describe())




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    topo_fraction:
    count    1920.000000
    mean        0.663333
    std         0.440783
    min         0.000000
    25%         0.000000
    50%         1.000000
    75%         1.000000
    max         1.000000
    Name: topo_fraction, dtype: float64





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.330 seconds)


.. _sphx_glr_download_auto_examples_14_surface_encoding.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 14_surface_encoding.ipynb <14_surface_encoding.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 14_surface_encoding.py <14_surface_encoding.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 14_surface_encoding.zip <14_surface_encoding.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_