{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "vx-intro",
   "metadata": {},
   "source": [
    "# Voxel segmentation and meshing\n",
    "\n",
    "Segment a voxel or grid orientation field (EBSD or gridded NF) into grains via graph clustering (Leiden) or flood-fill, then build a conformal hex mesh with CUBIT/SCULPT, using `VoxelMeshBuilder`. Use this when you have a gridded Euler-angle CSV or an FF `reconstruction_reformatted.csv` and want a segmented mesh.\n",
    "\n",
    "**Needs:** CUBIT/SCULPT (via `sculpt_config`); graph segmentation uses networkit (Leiden). Wrap the driver in `if __name__ == \"__main__\": main()`.\n",
    "\n",
    "<div class=\"admonition warning\">\n",
    "<p class=\"admonition-title\">Tier B: needs CUBIT/SCULPT</p>\n",
    "<p>This notebook needs CUBIT's <code>psculpt</code> and <code>epu</code>, which is not available in CI or Google Colab, so it is <strong>not executed when these docs are built</strong>. It ships as an annotated code listing with <strong>no stored output</strong> \u2014 nothing on this page is a hand-written or fabricated result. Run it in a configured environment (see the <a href=\"../install.rst\">installation guide</a>) to produce the figures, and run it from the <strong>repository root</strong> so the <code>mwe_data/</code> paths resolve.</p>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vx-inputs",
   "metadata": {},
   "source": [
    "## Inputs\n",
    "\n",
    "A merged CSV with `x,y,z,Eul0,Eul1,Eul2` (EBSD), or an FF `reconstruction_reformatted.csv` (pass `cell_id_col` and `angle_type=\"degrees\"`). See [concepts](../concepts.rst)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vx-recipe-md",
   "metadata": {},
   "source": [
    "## Recipe"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "vx-recipe-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "from graintrace.construct_voxel_mesh import VoxelMeshBuilder\n",
    "\n",
    "builder = VoxelMeshBuilder(\n",
    "    file_path=\"out/ebsd/EBSD_merged.csv\", save_dir=\"out/ebsd/mesh\",\n",
    "    euler_cols=[\"Eul0\", \"Eul1\", \"Eul2\"], angle_convention=\"bunge\",\n",
    "    angle_type=\"radians\", symmetry=\"432\",\n",
    ")\n",
    "merged_grid = builder.reconstruct(\n",
    "    apply_smoothing=True,\n",
    "    segmentation={\n",
    "        \"method\": \"graph\",                       # \"graph\" or \"flood\"\n",
    "        \"params\": {\"misorientation_tol\": 5.0,    # deg if angle_type=\"degrees\" else rad\n",
    "                   \"connectivity\": 26, \"grain_threshold_final\": 100},\n",
    "        \"graph_params\": {\n",
    "            \"segmenter\": \"leiden\", \"graph_mode\": \"grid\", \"manhattan_radius\": 2,\n",
    "            \"grid_tol\": 1e-6, \"n_jobs\": 10, \"weight_chunk_size\": 1_000_000,\n",
    "            \"reduce_edges_topweights_k\": 8, \"nodes_chunk\": 500_000, \"seed\": 42,\n",
    "            \"networkit_kwargs\": {\"gamma\": 0.001},   # lower gamma = fewer clusters\n",
    "            \"weight_cfg\": {\"mode\": \"rbf\", \"sigma\": None,\n",
    "                           \"sigma_auto\": {\"sample_size\": 20_000, \"random_state\": 42,\n",
    "                                          \"quantile\": 0.5}, \"power\": 2.0},\n",
    "            \"plot\": True,\n",
    "        },\n",
    "    },\n",
    ")\n",
    "mesh_path = builder.mesh(sculpt_config=sculpt_config, sculpt_options=sculpt_options,\n",
    "                         merged_grid=merged_grid)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vx-key-params",
   "metadata": {},
   "source": "## Key parameters\n\n- `segmentation.method`: `\"graph\"` (Leiden; better for complex textures) or `\"flood\"` (simpler, adds `batch_norm` / `grain_threshold` / `stop_count`). See [configuration](../configuration.rst).\n- `misorientation_tol` units follow `angle_type`; `connectivity` is 6 or 26.\n- Graph tuning: `networkit_kwargs[\"gamma\"]` (lower gives fewer, larger grains) and the `weight_cfg` RBF settings.\n- `sculpt_config` / `sculpt_options`: CUBIT hex meshing; see [configuration](../configuration.rst) and [meshing](meshing.ipynb)."
  },
  {
   "cell_type": "markdown",
   "id": "vx-outputs",
   "metadata": {},
   "source": [
    "## Outputs (in `save_dir`)\n",
    "\n",
    "- the segmented voxel grid `.npy`\n",
    "- `mesh.e`: the Exodus mesh\n",
    "- per-element MRP `orientations.csv`\n",
    "- optional VTK and diagnostic plots"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vx-gotchas",
   "metadata": {},
   "source": [
    "## Gotchas\n",
    "\n",
    "- FF-to-voxel path: an input `reconstruction_reformatted.csv` holds Euler angles in degrees, so pass `angle_type=\"degrees\"`. See [pitfalls](../pitfalls.rst).\n",
    "- Large grids: tune `n_jobs`, `weight_chunk_size`, and `nodes_chunk` for memory."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "vx-full-example",
   "metadata": {},
   "source": [
    "## Full example\n",
    "\n",
    "**Full script:** [examples/demonstrate_grid_segmentation_mesh.py](https://github.com/applied-material-modeling/graintrace/blob/main/examples/demonstrate_grid_segmentation_mesh.py)"
   ]
  }
 ],
 "metadata": {
  "nbsphinx": {
   "execute": "never"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}