.. _writing-kernel:

===============================================================================
Writing a kernel
===============================================================================

:Author: Bradley Chambers
:Contact: brad.chambers@gmail.com
:Date: 01/21/2015


PDAL's command-line application can be extended through the development of
kernel functions. In this tutorial, we will give a brief example.

The header
-------------------------------------------------------------------------------

First, we provide a full listing of the kernel header.

.. literalinclude:: ../../examples/writing-kernel/MyKernel.hpp
   :language: cpp

As with other plugins, the MyKernel class needs to have the following three methods declared for the plugin interface to be satisfied:

.. literalinclude:: ../../examples/writing-kernel/MyKernel.hpp
   :language: cpp
   :lines: 16-18


The source
-------------------------------------------------------------------------------

Again, we start with a full listing of the kernel source.

.. literalinclude:: ../../examples/writing-kernel/MyKernel.cpp
   :language: cpp

In your kernel implementation, you will use a macro defined in pdal_macros.
This macro registers the plugin with the Kernel factory. It is
only required by plugins.

.. literalinclude:: ../../examples/writing-kernel/MyKernel.cpp
   :language: cpp
   :lines: 23-29

A static plugin macro can also be used to integrate the kernel with the main code.
This will not be described here.  Using this as a shared plugin will be described later.

To build up a processing pipeline in this
example, we need to create two objects: the
PointTable and the StageFactory. The latter is
used to create the various stages that will be
used within the kernel.

.. literalinclude:: ../../examples/writing-kernel/MyKernel.cpp
   :language: cpp
   :lines: 60

The Reader is created from the StageFactory, and
is specified by the stage name, in this case an
LAS reader. For brevity, we provide the reader a
single option, the filename of the file to be
read.

.. literalinclude:: ../../examples/writing-kernel/MyKernel.cpp
   :language: cpp
   :lines: 62-65

The Filter is also created from the StageFactory.
Here, we create a decimation filter that will
pass every tenth point to subsequent stages. We
also specify the input to this stage, which is
the reader.

.. literalinclude:: ../../examples/writing-kernel/MyKernel.cpp
   :language: cpp
   :lines: 67-71

Finally, the Writer is created from the
StageFactory. This text writer, takes as input
the previous stage (the decimation filter) and
the output filename as its sole option.

.. literalinclude:: ../../examples/writing-kernel/MyKernel.cpp
   :language: cpp
   :lines: 73-77

The final two steps are to prepare and execute
the pipeline. This is achieved by calling prepare
and execute on the final stage.

.. literalinclude:: ../../examples/writing-kernel/MyKernel.cpp
   :language: cpp
   :lines: 78-79

When compiled, a dynamic library file will be created; in this case, ``libpdal_plugin_kernel_mykernel.dylib``

Put this file in whatever directory ``PDAL_DRIVER_PATH`` is pointing to.  Then, if you run ``pdal --help``, you should see ``mykernel`` listed in the possible commands.

To run this kernel, you would use ``pdal mykernel -i <input las file> -o <output text file>``.
