Writing a kernel

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.

// MyKernel.hpp

#pragma once

#include <pdal/Kernel.hpp>

#include <string>

namespace pdal
{

class PDAL_DLL MyKernel : public Kernel
{
public:
    MyKernel();

    std::string getName() const;
    int execute(); // override

private:
    void addSwitches(ProgramArgs& args);

    std::string m_input_file;
    std::string m_output_file;
};

} // namespace pdal

As with other plugins, the MyKernel class needs to return a name.

    std::string getName() const;

The source

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

// MyKernel.cpp

#include "MyKernel.hpp"

#include <pdal/Filter.hpp>
#include <pdal/Kernel.hpp>
#include <pdal/Options.hpp>
#include <pdal/PointTable.hpp>

#include <memory>
#include <string>


namespace pdal {

  static PluginInfo const s_info
  {
    "kernels.mykernel",
    "MyKernel",
    "http://link/to/documentation"
  };

  CREATE_SHARED_KERNEL(MyKernel, s_info);
  std::string MyKernel::getName() const { return s_info.name; }

  MyKernel::MyKernel() : Kernel()
  {}

  void MyKernel::addSwitches(ProgramArgs& args)
  {
      args.add("input,i", "Input filename", m_input_file).setPositional();
      args.add("output,o", "Output filename", m_output_file).setPositional();
  }

  int MyKernel::execute()
  {
    PointTable table;

    Stage& reader = makeReader(m_input_file, "readers.las");

    // Options should be added in the call to makeFilter, makeReader,
    // or makeWriter so that the system can override them with those
    // provided on the command line when applicable.
    Options filterOptions;
    filterOptions.add("step", 10);
    Stage& filter = makeFilter("filters.decimation", reader, filterOptions);

    Stage& writer = makeWriter(m_output_file, filter, "writers.text");
    writer.prepare(table);
    writer.execute(table);

    return 0;
  }

} // namespace pdal

In your kernel implementation, you will use a macro defined in pdal_macros. This macro registers the plugin with the PluginManager.

  CREATE_SHARED_KERNEL(MyKernel, s_info);

To build up a processing pipeline in this example, we need to create two objects: the pdal::PointTable.

  int MyKernel::execute()
  {
    PointTable table;

    Stage& reader = makeReader(m_input_file, "readers.las");

    // Options should be added in the call to makeFilter, makeReader,
    // or makeWriter so that the system can override them with those
    // provided on the command line when applicable.
    Options filterOptions;
    filterOptions.add("step", 10);
    Stage& filter = makeFilter("filters.decimation", reader, filterOptions);

    Stage& writer = makeWriter(m_output_file, filter, "writers.text");
    writer.prepare(table);
    writer.execute(table);

    return 0;
  }

To implement the actual kernel logic we implement execute(). In this case, the kernel reads a las file, decimates the data (eliminates some points) and writes the result to a text file. The base kernel class provides functions (makeReader, makeFilter, makeWriter) to create stages with options as desired. The pipeline that has been created can be run by preparing and executing the last stage in the pipeline.

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 --drivers, 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>.

Compilation

Set up a CMakeLists.txt file to compile your kernel against PDAL:

cmake_minimum_required(VERSION 3.13)
project(KernelTutorial)

find_package(PDAL 2.5 REQUIRED CONFIG)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_library(pdal_plugin_kernel_mykernel SHARED MyKernel.cpp)
target_link_libraries(pdal_plugin_kernel_mykernel PRIVATE ${PDAL_LIBRARIES})
target_include_directories(pdal_plugin_kernel_mykernel PRIVATE
                            ${PDAL_INCLUDE_DIRS})
target_link_directories(pdal_plugin_kernel_mykernel PRIVATE ${PDAL_LIBRARY_DIRS})