Commit 48824f46 authored by Mike Rye's avatar Mike Rye
Browse files

Updated README.

parent 863117ce
# Introduction
This plugin is brings the full functionality of the [Point Cloud Library (PCL)](http://www.pointclouds.org/) to ParaView in an extensible class hierarchy. Templates and BOOST's preprocessing library are used to generate conversion functions to handle all of PCL's point types with XYZ data. All PCL point clouds with spatial data can thus be converted to and from VTK PolyData instances losslessly, which allows the user to create full PCL workflows within ParaView.
This plugin aims to bring the full functionality of the [Point Cloud Library (PCL)](http://www.pointclouds.org/) to [ParaView](https://www.paraview.org/) in an easily extensible class hierarchy. The core of the plugin provides a class to convert PCL point clouds of any point type to and from VTK PolyData instances so that data can be passed seamlessly through a full ParaView workflow. This communication with ParaView is mostly handled by common base classes so that developers can focus on transforming point clouds.
# Installation
To build, install the required dependencies then change to the source directory and run the following commands:
~~~~~{.sh}
mkdir -p build
cd build
cmake ..
cmake --build .
~~~~~
## Dependencies
Dependencies are listed in the table below along with the version used during development and testing. Minimum required versions have not been determined yet.
| Dependency | Tested Version | Minimum Version |
| :---------: | :-------------: | :--------------: |
| ParaView | 5.6.0 | ? |
| ParaView | master | ? |
| PCL | 1.9 | ? |
| Eigen | 3.6.3 | ? |
| Boost | 1.68 | ? |
## PCL Configuration
The dependency on ParaView master is temporary and due to a minor issue with ParaView 5.6.0 that will be corrected in the next release (normally spring 2019).
### PCL Configuration
If PCL is compiled against VTK, segfaults may occur during plugin loading. Strangely, the error only appears during manual loading. To prevent this, either replace `find_package(VTK)` with `find_package(ParaView)` in PCL's CMakeLists.txt file or pass the following options to CMake when building PCL:
* `-DWITH_VTK:BOOL=ON`
* `-DWITH_VTK:BOOL=OFF`
* `-DBUILD_visualization:BOOL=OFF`
To enable OpenNI support, PCL must also be compiled with `-DWITH_OPENNI:BOOL=ON` or `-DWITH_OPENNI2:BOOL=ON` and the corresponding OpenNI library must be installed.
### Segfault Details For Reference
~~~~~
*** Process received signal ***
Signal: Segmentation fault (11)
Signal code: Address not mapped (1)
Failing at address: 0x1508
[ 0] /usr/lib/libc.so.6(+0x37e00)[0x7efe8b3cce00]
[ 1] /usr/lib/libvtkCommonSystem-pv5.6.so.1(_ZN11vtkTimerLog17MarkEventInternalEPKcN16vtkTimerLogEntry12LogEntryTypeEPS2_+0x1ea)[0x7efe87ed10aa]
[ 2] /usr/lib/libvtkCommonSystem-pv5.6.so.1(_ZN11vtkTimerLog14MarkStartEventEPKc+0x21)[0x7efe87ed1281]
[ 3] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN15vtkSMOutputPort18GetDataInformationEv+0x214)[0x7efe8b930f24]
[ 4] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN11vtkSMDomain23GetInputDataInformationEPKci+0x80)[0x7efe8b90b8c0]
[ 5] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN20vtkSMArrayListDomain6UpdateEP13vtkSMProperty+0x56)[0x7efe8b8edfa6]
[ 6] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN13vtkSMProperty13UpdateDomainsEv+0x49)[0x7efe8b93ae69]
[ 7] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN9vtkObject22vtkClassMemberCallbackI13vtkSMPropertyEclEPS_mPv+0x3b)[0x7efe8b94040b]
[ 8] /usr/lib/libvtkCommonCore-pv5.6.so.1(+0x325b0a)[0x7efe88e79b0a]
[ 9] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN18vtkSMProxyProperty9LoadStateEP15vtkPVXMLElementP17vtkSMProxyLocator+0x2a9)[0x7efe8b969989]
[10] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN10vtkSMProxy12LoadXMLStateEP15vtkPVXMLElementP17vtkSMProxyLocator+0x14c)[0x7efe8b95613c]
[11] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN20vtkSMDeserializerXML8NewProxyEjP17vtkSMProxyLocator+0x115)[0x7efe8b9096c5]
[12] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN17vtkSMProxyLocator11LocateProxyEj+0x1af)[0x7efe8b96471f]
[13] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN24vtkSMCompoundSourceProxy17ReadXMLAttributesEP24vtkSMSessionProxyManagerP15vtkPVXMLElement+0x27b)[0x7efe8b8ff51b]
[14] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN24vtkSMSessionProxyManager8NewProxyEP15vtkPVXMLElementPKcS3_S3_+0x2c7)[0x7efe8b9865a7]
[15] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN24vtkSMSessionProxyManager8NewProxyEPKcS1_S1_+0xb6)[0x7efe8b986a06]
[16] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN24vtkSMSessionProxyManager17GetPrototypeProxyEPKcS1_+0xf4)[0x7efe8b987f74]
[17] /usr/lib/libvtkpqApplicationComponents-pv5.6.so.1(_ZN23pqProxyGroupMenuManager9getActionERK7QStringS2_+0x19d)[0x7efe8d3ceeed]
[18] /usr/lib/libvtkpqApplicationComponents-pv5.6.so.1(_ZN23pqProxyGroupMenuManager12populateMenuEv+0x3c4)[0x7efe8d3d1254]
[19] /usr/lib/libvtkpqApplicationComponents-pv5.6.so.1(_ZN23pqProxyGroupMenuManager21lookForNewDefinitionsEv+0x16b)[0x7efe8d3d221b]
[20] /usr/lib/libvtkpqApplicationComponents-pv5.6.so.1(_ZN9vtkObject22vtkClassMemberCallbackI23pqProxyGroupMenuManagerEclEPS_mPv+0x3b)[0x7efe8d3d388b]
[21] /usr/lib/libvtkCommonCore-pv5.6.so.1(+0x325b0a)[0x7efe88e79b0a]
[22] /usr/lib/libvtkCommonCore-pv5.6.so.1(+0x325c32)[0x7efe88e79c32]
[23] /usr/lib/libvtkPVServerManagerCore-pv5.6.so.1(_ZN24vtkSMSessionProxyManager12ExecuteEventEP9vtkObjectmPv+0x15f)[0x7efe8b98553f]
[24] /usr/lib/libvtkCommonCore-pv5.6.so.1(+0x325c32)[0x7efe88e79c32]
[25] /usr/lib/libvtkCommonCore-pv5.6.so.1(+0x325c32)[0x7efe88e79c32]
[26] /usr/lib/libvtkPVServerImplementationCore-pv5.6.so.1(_ZN27vtkSIProxyDefinitionManager20LoadConfigurationXMLEP15vtkPVXMLElementb+0x2f1)[0x7efe899dacb1]
[27] /usr/lib/libvtkPVServerImplementationCore-pv5.6.so.1(_ZN27vtkSIProxyDefinitionManager30LoadConfigurationXMLFromStringEPKcb+0x6c)[0x7efe899dad7c]
[28] /usr/lib/libvtkPVServerImplementationCore-pv5.6.so.1(_ZN27vtkSIProxyDefinitionManager12HandlePluginEP11vtkPVPlugin+0xdb)[0x7efe899dae7b]
[29] /usr/lib/libvtkPVServerImplementationCore-pv5.6.so.1(_ZN9vtkObject22vtkClassMemberCallbackI27vtkSIProxyDefinitionManagerEclEPS_mPv+0x69)[0x7efe899e09b9]
*** End of error message ***
~~~~~
# Developers
## Basic
`PCLPassThroughFilter` has been commented to provide a starting point for the development of new filters. In general, a new filter will only require 3 files to be copied and modified from one of the existing filters: the VTK class source and header files and the server manager proxy XML file (e.g. filter/vtkPCLPassThroughFilter.h, filter/vtkPCLPassThroughFilter.cxx, xml/PCLPassThroughFilter.xml).
### VTK Header
* Declare minimal VTK boilerplate code (copy-paste from existing filters and update the names).
* Declare the parameters as members of the VTK class along with setters and getters using the standard VTK macros (e.g. `vtkGetMacro`, `vtkSetMacro`, `vtkSetVector2Macro`, ...).
* Declare the private method invoked by the parent class's RequestData method (`ApplyPCLFilter` for filters, `LoadPCLReader` for readers, etc.)
* Declare any additional private internal methods needed by the aforementioned method.
### VTK Source
* Define minimal VTK boilerplate code (copy-paste from existing filters and update the names).
* Define the other declared methods. The general approach is to use vtkPCLConversions to determine the point type index of the input PolyData instance and then invoke a templated method that accepts the point type as a template parameter to handle the actual conversions. This is much simpler than it may initially sound and requires only 4 lines of code. The templated function then handles the actual conversion. This approach can be nested for multiple inputs of arbitrary PCL point type. The various `PCLP_INVOKE_WITH_*_POINT_TYPE` macros are provided for this purpose.
### Server Manager Proxy
* Expose and document the desired parameters of the filter and provide default values. These should match the names and values declared in the header, which in turn should match the names used in PCL.
* Add the filter to the PCL category, set the number of inputs, etc.
This usually just means copy-pasting an existing proxy and updating its name, documentation and parameters.
# Developer Guidelines
## Beyond Basic
One goal of this project is to eventually provide filters for all PCL filter functions. Ideally these filters should simply convert the input data to a PCL cloud, call the function, then convert the cloud back. All parameters of the function should be exposed via the ServerManager proxy so that a complete PCL workflow can be recreated via ParaView. These filters should follow the format of existing filters whenever possible, with each group (e.g. 2-input filters) using the same base class (e.g. vtkPCLFilter2). The names of all filter parameters should be identical to those of the PCL filter that it wraps.
It is possible to create filters with multiple inputs, some of which may even be optional. The `FPFHEstimationFilter2` provides an example of this. The same approach can and will be extended to filters with more inputs as the library grows. Although not yet implemented, it is also possible to create VTK filters with multiple outputs. Developers that wish to add new filters for which there currently is no base class (e.g. `vtkPCLFilter3` at the time of writing) should create the base class using the others as a model.
Filters that do not correspond directly to a single PCL function should use the "PCLB" prefix (PCL-based) instead of "PCL" and should start their proxy descriptions with "PCL-based". The parameters of all functions used in the filter should be exposed to make these compound filters as versatile as possible. In general, compound filters should be avoided whenever possible, but the need for simplified or faster workflows that omit intermittent conversions may not always permit this.
Ideally each filter should correspond as closely as possible to a single PCL functionality (e.g. `PassThrough`, `NormalEstimation`, `VoxelGrid`). In such cases, the name of the filter and class should use the PCL filter to signify that it is essentially a pure PCL function. In some cases this is nevertheless impossible, such as when intermediate steps and PolyData-inconvertible data objects are required. Filters that involve intermediate steps should use the PCLB prefix to indicate that they are PCL-based but not pure PCL). All internal parameters should be exposed via the server manager proxy to make the filter as generic as possible.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment