tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Laserchicken tutorial\n",
    "This document shows how Laserchicken can be used to calculate features that describe a point cloud."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load a las file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from laserchicken import load\n",
    "point_cloud = load('testdata/AHN3.las')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'vertex': {'x': {'type': 'float64',\n",
       "   'data': array([131999.984125, 131997.625125, 131998.547125, ..., 132501.531125,\n",
       "          132501.391125, 132500.641125])},\n",
       "  'y': {'type': 'float64',\n",
       "   'data': array([549718.375, 549723.875, 549722.875, ..., 549966.313, 549964.875,\n",
       "          549964.563])},\n",
       "  'z': {'type': 'float64',\n",
       "   'data': array([-0.34100002, -0.26600002, -0.26000002, ..., -0.24100002,\n",
       "          -0.24100002, -0.24000002])},\n",
       "  'raw_classification': {'type': 'uint8',\n",
       "   'data': array([9, 9, 9, ..., 9, 9, 9], dtype=uint8)},\n",
       "  'gps_time': {'type': 'float64',\n",
       "   'data': array([78563787.97322202, 78563787.93570042, 78563787.93571067, ...,\n",
       "          78563778.28828931, 78563778.3107884 , 78563778.32578015])},\n",
       "  'intensity': {'type': 'uint16',\n",
       "   'data': array([ 41, 152,  12, ...,  10,  15,  10], dtype=uint16)}},\n",
       " 'log': [{'time': '2022-09-05 12:50:13.438169',\n",
       "   'module': 'laserchicken.io.load',\n",
       "   'parameters': {'path': 'testdata/AHN3.las', 'args': ()},\n",
       "   'version': '0.6.0'}]}"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "point_cloud"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Normalize data\n",
    "Adds the attribute 'normaiized_height' to the point cloud. Note that data is added to the given point cloud  in place "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'vertex': {'x': {'type': 'float64',\n",
       "   'data': array([131999.984125, 131997.625125, 131998.547125, ..., 132501.531125,\n",
       "          132501.391125, 132500.641125])},\n",
       "  'y': {'type': 'float64',\n",
       "   'data': array([549718.375, 549723.875, 549722.875, ..., 549966.313, 549964.875,\n",
       "          549964.563])},\n",
       "  'z': {'type': 'float64',\n",
       "   'data': array([-0.34100002, -0.26600002, -0.26000002, ..., -0.24100002,\n",
       "          -0.24100002, -0.24000002])},\n",
       "  'raw_classification': {'type': 'uint8',\n",
       "   'data': array([9, 9, 9, ..., 9, 9, 9], dtype=uint8)},\n",
       "  'gps_time': {'type': 'float64',\n",
       "   'data': array([78563787.97322202, 78563787.93570042, 78563787.93571067, ...,\n",
       "          78563778.28828931, 78563778.3107884 , 78563778.32578015])},\n",
       "  'intensity': {'type': 'uint16',\n",
       "   'data': array([ 41, 152,  12, ...,  10,  15,  10], dtype=uint16)},\n",
       "  'normalized_height': {'type': 'float64',\n",
       "   'data': array([1.236, 1.311, 1.317, ..., 1.336, 1.336, 1.337])}},\n",
       " 'log': [{'time': '2022-09-05 12:50:13.438169',\n",
       "   'module': 'laserchicken.io.load',\n",
       "   'parameters': {'path': 'testdata/AHN3.las', 'args': ()},\n",
       "   'version': '0.6.0'},\n",
       "  {'time': '2022-09-05 12:50:13.495605',\n",
       "   'module': 'laserchicken.normalize',\n",
       "   'parameters': {'cell_size': None},\n",
       "   'version': '0.6.0'}]}"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from laserchicken.normalize import normalize\n",
    "normalize(point_cloud)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'vertex': {'x': {'type': 'float64',\n",
       "   'data': array([131999.984125, 131997.625125, 131998.547125, ..., 132501.531125,\n",
       "          132501.391125, 132500.641125])},\n",
       "  'y': {'type': 'float64',\n",
       "   'data': array([549718.375, 549723.875, 549722.875, ..., 549966.313, 549964.875,\n",
       "          549964.563])},\n",
       "  'z': {'type': 'float64',\n",
       "   'data': array([-0.34100002, -0.26600002, -0.26000002, ..., -0.24100002,\n",
       "          -0.24100002, -0.24000002])},\n",
       "  'raw_classification': {'type': 'uint8',\n",
       "   'data': array([9, 9, 9, ..., 9, 9, 9], dtype=uint8)},\n",
       "  'gps_time': {'type': 'float64',\n",
       "   'data': array([78563787.97322202, 78563787.93570042, 78563787.93571067, ...,\n",
       "          78563778.28828931, 78563778.3107884 , 78563778.32578015])},\n",
       "  'intensity': {'type': 'uint16',\n",
       "   'data': array([ 41, 152,  12, ...,  10,  15,  10], dtype=uint16)},\n",
       "  'normalized_height': {'type': 'float64',\n",
       "   'data': array([1.236, 1.311, 1.317, ..., 1.336, 1.336, 1.337])}},\n",
       " 'log': [{'time': '2022-09-05 12:50:13.438169',\n",
       "   'module': 'laserchicken.io.load',\n",
       "   'parameters': {'path': 'testdata/AHN3.las', 'args': ()},\n",
       "   'version': '0.6.0'},\n",
       "  {'time': '2022-09-05 12:50:13.495605',\n",
       "   'module': 'laserchicken.normalize',\n",
       "   'parameters': {'cell_size': None},\n",
       "   'version': '0.6.0'}]}"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "point_cloud"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Filter points inside a polygon\n",
    "We filter points within a polygon"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "from laserchicken.filter import select_polygon\n",
    "polygon = \"POLYGON(( 131963.984125 549718.375000,\" + \\\n",
    "                   \" 132000.000125 549718.375000,\" + \\\n",
    "                   \" 132000.000125 549797.063000,\" + \\\n",
    "                   \" 131963.984125 549797.063000,\" + \\\n",
    "                   \" 131963.984125 549718.375000))\"\n",
    "point_cloud = select_polygon(point_cloud, polygon)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Filter points by attribute threshold"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "from laserchicken.filter import select_above, select_below\n",
    "points_below_1_meter = select_below(point_cloud, 'normalized_height', 1)\n",
    "points_above_1_meter = select_above(point_cloud, 'normalized_height', 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Compute neighbors\n",
    "Computer neighbors for every point in the point cloud. This means that the target point cloud should contain the same points as the environment point cloud. The target point cloud contains the point at which the neighbors should be calculated.\n",
    "\n",
    "The code below finds for every target point, the neighbors within a Spherical neighborhood with radius of 5 meters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "from laserchicken import compute_neighborhoods\n",
    "from laserchicken import build_volume\n",
    "targets = point_cloud\n",
    "volume = build_volume('sphere', radius=5)\n",
    "neighborhoods = compute_neighborhoods(point_cloud, targets, volume)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Calculate features"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cylinder size in Bytes: 1262794583.0369534\n",
      "Memory size in Bytes: 17179869184\n",
      "Start tree creation\n",
      "Done with env tree creation\n",
      "Done with target tree creation\n",
      "Extracting feature(s) \"['eigenv_1', 'eigenv_2', 'eigenv_3', 'normal_vector_1', 'normal_vector_2', 'normal_vector_3', 'slope']\"Extracting feature(s) \"['eigenv_1', 'eigenv_2', 'eigenv_3', 'normal_vector_1', 'normal_vector_2', 'normal_vector_3', 'slope']\" took 0.25 seconds\n",
      "Extracting feature(s) \"['mean_z', 'std_z', 'coeff_var_z']\"Extracting feature(s) \"['mean_z', 'std_z', 'coeff_var_z']\" took 0.19 seconds\n",
      "The following unrequested features were calculated as a side effect, but will not be returned: ['normal_vector_3', 'normal_vector_2', 'normal_vector_1', 'eigenv_3', 'eigenv_2', 'eigenv_1', 'coeff_var_z']\n"
     ]
    }
   ],
   "source": [
    "from laserchicken import compute_features\n",
    "compute_features(point_cloud, neighborhoods, targets, ['std_z','mean_z','slope'], volume)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Calculate parameterized features\n",
    "We add 4 parameterized features."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "from laserchicken import register_new_feature_extractor\n",
    "from laserchicken.feature_extractor.band_ratio_feature_extractor import BandRatioFeatureExtractor\n",
    "register_new_feature_extractor(BandRatioFeatureExtractor(None,1,data_key='normalized_height'))\n",
    "register_new_feature_extractor(BandRatioFeatureExtractor(1,2,data_key='normalized_height'))\n",
    "register_new_feature_extractor(BandRatioFeatureExtractor(2,None,data_key='normalized_height'))\n",
    "register_new_feature_extractor(BandRatioFeatureExtractor(None,0,data_key='z'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Print a list of all available feature names and notice the parameterized features we just registered, 'band_ratio_1<z<2'."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['band_ratio_1_normalized_height_2',\n",
       " 'band_ratio_2_normalized_height',\n",
       " 'band_ratio_2_normalized_height_3',\n",
       " 'band_ratio_3_normalized_height',\n",
       " 'band_ratio_normalized_height_1',\n",
       " 'band_ratio_z_0',\n",
       " 'coeff_var_intensity',\n",
       " 'coeff_var_normalized_height',\n",
       " 'coeff_var_z',\n",
       " 'density_absolute_mean_normalized_height',\n",
       " 'density_absolute_mean_z',\n",
       " 'echo_ratio',\n",
       " 'eigenv_1',\n",
       " 'eigenv_2',\n",
       " 'eigenv_3',\n",
       " 'entropy_normalized_height',\n",
       " 'entropy_z',\n",
       " 'kurto_normalized_height',\n",
       " 'kurto_z',\n",
       " 'max_intensity',\n",
       " 'max_normalized_height',\n",
       " 'max_z',\n",
       " 'mean_intensity',\n",
       " 'mean_normalized_height',\n",
       " 'mean_z',\n",
       " 'median_normalized_height',\n",
       " 'median_z',\n",
       " 'min_intensity',\n",
       " 'min_normalized_height',\n",
       " 'min_z',\n",
       " 'normal_vector_1',\n",
       " 'normal_vector_2',\n",
       " 'normal_vector_3',\n",
       " 'perc_100_normalized_height',\n",
       " 'perc_100_z',\n",
       " 'perc_10_normalized_height',\n",
       " 'perc_10_z',\n",
       " 'perc_11_normalized_height',\n",
       " 'perc_11_z',\n",
       " 'perc_12_normalized_height',\n",
       " 'perc_12_z',\n",
       " 'perc_13_normalized_height',\n",
       " 'perc_13_z',\n",
       " 'perc_14_normalized_height',\n",
       " 'perc_14_z',\n",
       " 'perc_15_normalized_height',\n",
       " 'perc_15_z',\n",
       " 'perc_16_normalized_height',\n",
       " 'perc_16_z',\n",
       " 'perc_17_normalized_height',\n",
       " 'perc_17_z',\n",
       " 'perc_18_normalized_height',\n",
       " 'perc_18_z',\n",
       " 'perc_19_normalized_height',\n",
       " 'perc_19_z',\n",
       " 'perc_1_normalized_height',\n",
       " 'perc_1_z',\n",
       " 'perc_20_normalized_height',\n",
       " 'perc_20_z',\n",
       " 'perc_21_normalized_height',\n",
       " 'perc_21_z',\n",
       " 'perc_22_normalized_height',\n",
       " 'perc_22_z',\n",
       " 'perc_23_normalized_height',\n",
       " 'perc_23_z',\n",
       " 'perc_24_normalized_height',\n",
       " 'perc_24_z',\n",
       " 'perc_25_normalized_height',\n",
       " 'perc_25_z',\n",
       " 'perc_26_normalized_height',\n",
       " 'perc_26_z',\n",
       " 'perc_27_normalized_height',\n",
       " 'perc_27_z',\n",
       " 'perc_28_normalized_height',\n",
       " 'perc_28_z',\n",
       " 'perc_29_normalized_height',\n",
       " 'perc_29_z',\n",
       " 'perc_2_normalized_height',\n",
       " 'perc_2_z',\n",
       " 'perc_30_normalized_height',\n",
       " 'perc_30_z',\n",
       " 'perc_31_normalized_height',\n",
       " 'perc_31_z',\n",
       " 'perc_32_normalized_height',\n",
       " 'perc_32_z',\n",
       " 'perc_33_normalized_height',\n",
       " 'perc_33_z',\n",
       " 'perc_34_normalized_height',\n",
       " 'perc_34_z',\n",
       " 'perc_35_normalized_height',\n",
       " 'perc_35_z',\n",
       " 'perc_36_normalized_height',\n",
       " 'perc_36_z',\n",
       " 'perc_37_normalized_height',\n",
       " 'perc_37_z',\n",
       " 'perc_38_normalized_height',\n",
       " 'perc_38_z',\n",
       " 'perc_39_normalized_height',\n",
       " 'perc_39_z',\n",
       " 'perc_3_normalized_height',\n",
       " 'perc_3_z',\n",
       " 'perc_40_normalized_height',\n",
       " 'perc_40_z',\n",
       " 'perc_41_normalized_height',\n",
       " 'perc_41_z',\n",
       " 'perc_42_normalized_height',\n",
       " 'perc_42_z',\n",
       " 'perc_43_normalized_height',\n",
       " 'perc_43_z',\n",
       " 'perc_44_normalized_height',\n",
       " 'perc_44_z',\n",
       " 'perc_45_normalized_height',\n",
       " 'perc_45_z',\n",
       " 'perc_46_normalized_height',\n",
       " 'perc_46_z',\n",
       " 'perc_47_normalized_height',\n",
       " 'perc_47_z',\n",
       " 'perc_48_normalized_height',\n",
       " 'perc_48_z',\n",
       " 'perc_49_normalized_height',\n",
       " 'perc_49_z',\n",
       " 'perc_4_normalized_height',\n",
       " 'perc_4_z',\n",
       " 'perc_50_normalized_height',\n",
       " 'perc_50_z',\n",
       " 'perc_51_normalized_height',\n",
       " 'perc_51_z',\n",
       " 'perc_52_normalized_height',\n",
       " 'perc_52_z',\n",
       " 'perc_53_normalized_height',\n",
       " 'perc_53_z',\n",
       " 'perc_54_normalized_height',\n",
       " 'perc_54_z',\n",
       " 'perc_55_normalized_height',\n",
       " 'perc_55_z',\n",
       " 'perc_56_normalized_height',\n",
       " 'perc_56_z',\n",
       " 'perc_57_normalized_height',\n",
       " 'perc_57_z',\n",
       " 'perc_58_normalized_height',\n",
       " 'perc_58_z',\n",
       " 'perc_59_normalized_height',\n",
       " 'perc_59_z',\n",
       " 'perc_5_normalized_height',\n",
       " 'perc_5_z',\n",
       " 'perc_60_normalized_height',\n",
       " 'perc_60_z',\n",
       " 'perc_61_normalized_height',\n",
       " 'perc_61_z',\n",
       " 'perc_62_normalized_height',\n",
       " 'perc_62_z',\n",
       " 'perc_63_normalized_height',\n",
       " 'perc_63_z',\n",
       " 'perc_64_normalized_height',\n",
       " 'perc_64_z',\n",
       " 'perc_65_normalized_height',\n",
       " 'perc_65_z',\n",
       " 'perc_66_normalized_height',\n",
       " 'perc_66_z',\n",
       " 'perc_67_normalized_height',\n",
       " 'perc_67_z',\n",
       " 'perc_68_normalized_height',\n",
       " 'perc_68_z',\n",
       " 'perc_69_normalized_height',\n",
       " 'perc_69_z',\n",
       " 'perc_6_normalized_height',\n",
       " 'perc_6_z',\n",
       " 'perc_70_normalized_height',\n",
       " 'perc_70_z',\n",
       " 'perc_71_normalized_height',\n",
       " 'perc_71_z',\n",
       " 'perc_72_normalized_height',\n",
       " 'perc_72_z',\n",
       " 'perc_73_normalized_height',\n",
       " 'perc_73_z',\n",
       " 'perc_74_normalized_height',\n",
       " 'perc_74_z',\n",
       " 'perc_75_normalized_height',\n",
       " 'perc_75_z',\n",
       " 'perc_76_normalized_height',\n",
       " 'perc_76_z',\n",
       " 'perc_77_normalized_height',\n",
       " 'perc_77_z',\n",
       " 'perc_78_normalized_height',\n",
       " 'perc_78_z',\n",
       " 'perc_79_normalized_height',\n",
       " 'perc_79_z',\n",
       " 'perc_7_normalized_height',\n",
       " 'perc_7_z',\n",
       " 'perc_80_normalized_height',\n",
       " 'perc_80_z',\n",
       " 'perc_81_normalized_height',\n",
       " 'perc_81_z',\n",
       " 'perc_82_normalized_height',\n",
       " 'perc_82_z',\n",
       " 'perc_83_normalized_height',\n",
       " 'perc_83_z',\n",
       " 'perc_84_normalized_height',\n",
       " 'perc_84_z',\n",
       " 'perc_85_normalized_height',\n",
       " 'perc_85_z',\n",
       " 'perc_86_normalized_height',\n",
       " 'perc_86_z',\n",
       " 'perc_87_normalized_height',\n",
       " 'perc_87_z',\n",
       " 'perc_88_normalized_height',\n",
       " 'perc_88_z',\n",
       " 'perc_89_normalized_height',\n",
       " 'perc_89_z',\n",
       " 'perc_8_normalized_height',\n",
       " 'perc_8_z',\n",
       " 'perc_90_normalized_height',\n",
       " 'perc_90_z',\n",
       " 'perc_91_normalized_height',\n",
       " 'perc_91_z',\n",
       " 'perc_92_normalized_height',\n",
       " 'perc_92_z',\n",
       " 'perc_93_normalized_height',\n",
       " 'perc_93_z',\n",
       " 'perc_94_normalized_height',\n",
       " 'perc_94_z',\n",
       " 'perc_95_normalized_height',\n",
       " 'perc_95_z',\n",
       " 'perc_96_normalized_height',\n",
       " 'perc_96_z',\n",
       " 'perc_97_normalized_height',\n",
       " 'perc_97_z',\n",
       " 'perc_98_normalized_height',\n",
       " 'perc_98_z',\n",
       " 'perc_99_normalized_height',\n",
       " 'perc_99_z',\n",
       " 'perc_9_normalized_height',\n",
       " 'perc_9_z',\n",
       " 'point_density',\n",
       " 'pulse_penetration_ratio',\n",
       " 'range_intensity',\n",
       " 'range_normalized_height',\n",
       " 'range_z',\n",
       " 'sigma_z',\n",
       " 'skew_normalized_height',\n",
       " 'skew_z',\n",
       " 'slope',\n",
       " 'std_intensity',\n",
       " 'std_normalized_height',\n",
       " 'std_z',\n",
       " 'var_normalized_height',\n",
       " 'var_z']"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from laserchicken.feature_extractor.feature_extraction import list_feature_names\n",
    "sorted(list_feature_names())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Recalculate neighbors and calculate the parameterized feature\n",
    "Neighbors is a generator and can only be iterated once. We therefore recalculate them here. If we would want to do multiple calculations without recalculating the neighbors, we could copy the neighbors to a list. This is not done by default because neighbors can quickly grow quite large so that available RAM unnecessarily becomes the bottle neck."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cylinder size in Bytes: 1262794583.0369534\n",
      "Memory size in Bytes: 17179869184\n",
      "Start tree creation\n",
      "Done with env tree creation\n",
      "Done with target tree creation\n",
      "Extracting feature(s) \"['band_ratio_1_normalized_height_2']\"Extracting feature(s) \"['band_ratio_1_normalized_height_2']\" took 0.08 seconds\n"
     ]
    }
   ],
   "source": [
    "cylinder = build_volume('infinite cylinder', radius=5)\n",
    "neighborhoods = compute_neighborhoods(point_cloud, targets, cylinder)\n",
    "compute_features(point_cloud, neighborhoods, targets, ['band_ratio_1_normalized_height_2'], cylinder)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Write result to ply file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "from laserchicken import export\n",
    "export(point_cloud, 'my_output.ply')"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}