Merge pull request #9 from alexandrainst/8-add-installation-and-fix-image-loading-in-readme

8 add installation and fix image loading in readme

Author: tpprytula

README.md

@@ -3,35 +3,57 @@
 A Python implementation of an SN-Graph skeletonisation algorithm. Based on the article *SN-Graph: a Minimalist 3D Object Representation for Classification* [arXiv:2105.14784](https://arxiv.org/abs/2105.14784).
 
 
-![Example of a binary image and the skeletal graph](/assets/horse_graph.png "SN-graph generated out of an scikit-image's horse image.")
+![Example of a binary image and the skeletal graph](https://raw.githubusercontent.com/alexandrainst/sn-graph/main/assets/horse_graph.png "SN-graph generated out of an scikit-image's horse image.")
 
 ## Description
 
-SN-Graph works by:
+Given a binary image/volume representing a shape, SN-Graph works by:
 
-1. Creating vertices as centres of spheres inscribed in the image, where one balances the size of the spheres with their coverage of the shape, and pariwise distances from one another.
+1. Creating vertices as centres of spheres inscribed in the shape, where one balances the size of the spheres with their coverage of the shape, and pariwise distances from one another.
 3. Adding edges between the neighbouring spheres, subject to a few common-sense criteria.
 
 The resulting graph serves as a lightweight 1-dimensional representation of the original image, potentially useful for further analysis.
 
+## Installation
+
+```bash
+pip install sn-graph
+```
+or
+
+```bash
+poetry add sn-graph
+```
+
 ## Basic Usage
 
+See notebooks [demo_sn-graph](notebooks/demo_sn-graph.ipynb) and [3d_demo](notebooks/3D_demo.ipynb) for 2D and 3D demo, respectively. Notebook [mnist_classification](notebooks/mnist_classification.ipynb) has some good stuff too!
+
 ```python
 import numpy as np
 import sn_graph as sn
 
 # Create a simple square image
-img = np.zeros((100, 100))
-img[40:60, 40:60] = 1  # Create a square region
+img = np.zeros((256, 256))
+img[20:236, 20:236] = 1  # Create a square region
 
 # Generate the SN graph
-centers, edges = sn.create_sn_graph(
+centers, edges, sdf_array = sn.create_sn_graph(
     img,
-    max_num_vertices=10,
-    edge_threshold=1.0
+    max_num_vertices=15,
+    minimal_sphere_radius=1.0,
+    return_sdf=True
 )
 
+import matplotlib.pyplot as plt
+
+#Draw graph on top of the image and plot it
+graph_image=sn.draw_sn_graph(centers, edges, sdf_array, background_image=img)
+
+plt.imshow(graph_image)
+plt.show()
 ```
+<img src="https://raw.githubusercontent.com/alexandrainst/sn-graph/main/assets/square_readme.png" alt="SN-Graph drawn on top of the square" width="500">
 
 ## Key Parameters
 
@@ -40,6 +62,7 @@ centers, edges = sn.create_sn_graph(
 - `edge_threshold`: Threshold for determining what portion of an edge must be contained within the shape
 - `minimal_sphere_radius`: Minimum radius allowed for spheres
 - `edge_sphere_threshold`: Threshold value for deciding how close can an edge be to a non-enpdpoint spheres
+- `return_sdf`: Whether to return signed distance field array computed by the algorithm (neccessary to extract radii of spheres)
 
 ## Authors
 - Tomasz Prytuła (<tomasz.prytula@alexandra.dk>)

assets/square_readme.png

@@ -1,5 +1,14 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## A 3d Demo\n",
+    "\n",
+    "The notebook shows how to extract SN-Graph out of a 3D volume."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -28,7 +37,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# local voxelise allos to fill the inside of the mesh with positive values\n",
+    "# local voxelise allows to fill the inside of the mesh with positive values which is needed for sdf computation\n",
     "voxels = trimesh.voxel.creation.local_voxelize(\n",
     "    mesh, point=(0, 0, 0), radius=300, pitch=0.5, fill=True\n",
     ")\n",

notebooks/3D_demo.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "## A Mnist classification using skeletal graphs. \n",
     "\n",
-    "A demo on using SN-graphs as inputs to Graph Nueral Networks. The model achieves roughly 90% accuracy, "
+    "A demo on using SN-graphs as inputs to Graph Neural Networks. The model achieves roughly 90% accuracy, "
    ]
   },
   {