Examples/Example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using foambryo\n",
    "\n",
    "In this notebook, we'll see:\n",
    "- How to install foambryo,\n",
    "- What are the inputs of foambryo,\n",
    "- How to compute relative tensions and pressures insides cells,\n",
    "- How to plot these forces using the foambryo viewer.\n",
    "\n",
    "# 0) Installation\n",
    "\n",
    "Foambryo is available on pyPI such that you can just use pip !\n",
    "\n",
    "- if you don't need any visualization, use `pip install foambryo`.\n",
    "- if you want to use the foambryo viewer to visualize the forces on a 3D mesh, use `pip install \"foambryo[viewing]\"`.\n",
    "\n",
    "In this notebook we'll show how to visualize the results, so we choose the later option."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! pip install \"foambryo[viewing]\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1) Prepare an inference mesh\n",
    "\n",
    "Foambryo actually computes tensions and pressures from a datastructure called a DCEL mesh. Foambryo can create such a mesh from 2 sources:\n",
    "- an instance segmentation mask, using the Delaunay-Watershed-3D algorithm,\n",
    "- a multimaterial mesh.\n",
    "\n",
    "We provide easy functions to have a mesh ready for force inference:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import skimage.io as io\n",
    "from dw3d.io import load_rec\n",
    "from foambryo import dcel_mesh_from_file, dcel_mesh_from_multimaterial_mesh, dcel_mesh_from_segmentation_mask\n",
    "\n",
    "# 1) From a segmentation mask\n",
    "image_path = \"../data/Segmentations/Benchmark_labels.tif\"\n",
    "segmentation_mask = io.imread(image_path)  # open segmentation image.\n",
    "# If here you have a problem, make sure you have git lfs installed and run git lfs pull to really download this large file.\n",
    "\n",
    "dcel_mesh_1 = dcel_mesh_from_segmentation_mask(segmentation_mask, min_distance=3, print_info=True)  # DCEL mesh ready for force inference !\n",
    "# Note: mesh reconstruction from a segmentation mask can take some time.\n",
    "\n",
    "# 2) From a multimaterial mesh file (3D triangle mesh + material data)\n",
    "dcel_mesh_2 = dcel_mesh_from_file(\"../data/Meshes/simple_mesh.vtk\")\n",
    "\n",
    "# 3) From an opened multimaterial mesh (3 arrays: points, triangles, labels/materials)\n",
    "# Here we open a mesh to simulate the situation:\n",
    "points, triangles, labels = load_rec(\"../data/Meshes/Benchmark_original_mesh.rec\")\n",
    "dcel_mesh_3 = dcel_mesh_from_multimaterial_mesh(points, triangles, labels)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2) Force Inference\n",
    "\n",
    "Now that we have a DCEL mesh, we can easily compute relative pressures between cells and relative tensions at interfaces between cells (or with the exterior region)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from foambryo import infer_forces\n",
    "\n",
    "# select mesh\n",
    "dcel_mesh = dcel_mesh_1\n",
    "\n",
    "# infer both tensions and pressures\n",
    "tensions, pressures = infer_forces(dcel_mesh)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The outputs are simple data structures:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# pressures is a dictionary that maps cell index to pressure force. 0 is the exterior.\n",
    "print(f\"{pressures=}\")\n",
    "\n",
    "# tensions is a dictionary that maps cells interfaces (cell index 1, cell index 2) to tension force. 0 is the exterior.\n",
    "print(f\"{tensions=}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also compute tensions only, but for the pressures, you need to have first computed the tensions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from foambryo import infer_pressures, infer_tensions\n",
    "\n",
    "tensions = infer_tensions(dcel_mesh)\n",
    "\n",
    "pressures = infer_pressures(dcel_mesh, tensions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An important thing to understand is that we compute relative tensions and pressures. As such, when computing pressures, you need to give a base pressure (the pressure of the exterior, the medium) ; when computing tensions, you need to give a mean tension.\n",
    "\n",
    "By default, the base pressure is 0 while the mean tension is 1. You can always set it as desired:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# previous lines where equivalent to these:\n",
    "tensions, pressures = infer_forces(dcel_mesh, mean_tension=1, base_pressure=0)\n",
    "tensions = infer_tensions(dcel_mesh, mean_tension=1)\n",
    "pressures = infer_pressures(dcel_mesh, tensions, base_pressure=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, foambryo implements several strategies to compute tensions and pressures. The default strategies give good results, but you can explore the other strategies if you want."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from foambryo import PressureComputationMethod, TensionComputationMethod\n",
    "\n",
    "print(f\"Available pressure computation methods: {[pressure_method.name for pressure_method in PressureComputationMethod]}.\")\n",
    "\n",
    "print(f\"Available tension computation methods: {[tension_method.name for tension_method in TensionComputationMethod]}.\")\n",
    "\n",
    "# previous lines where equivalent to these:\n",
    "tensions, pressures = infer_forces(dcel_mesh, mode_tension=TensionComputationMethod.YoungDupre, mode_pressure=PressureComputationMethod.Variational)\n",
    "tensions = infer_tensions(dcel_mesh, mode=TensionComputationMethod.YoungDupre)\n",
    "pressures = infer_pressures(dcel_mesh, tensions, mode=PressureComputationMethod.Variational)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3) Plotting forces\n",
    "\n",
    "Now that we have tensions and pressures, foambryo can also plot the mesh with the values.\n",
    "\n",
    "To plot pressures:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from foambryo.viewing import plot_pressure_inference\n",
    "\n",
    "# Note: only the mesh in necessary. If pressures are not provided, they'll be computed.\n",
    "plot_pressure_inference(dcel_mesh, pressures)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To plot tensions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from foambryo.viewing import plot_tension_inference\n",
    "\n",
    "# Note: only the mesh in necessary. If tensions are not provided, they'll be computed.\n",
    "# For tensions, it's better to scatter the cells\n",
    "plot_tension_inference(dcel_mesh, tensions, scattered=True, scatter_coeff=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To plot both on the same viewer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from foambryo.viewing import plot_force_inference\n",
    "\n",
    "plot_force_inference(dcel_mesh, tensions, pressures)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Many more data can be plotted, such s the curvature, the area and volume derivatives..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_force_inference(dcel_mesh, tensions, pressures, scalar_quantities=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Plotting functions have many interesting parameters, don't hesitate to play with them !"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}