pdal / java   2.4.0

Website GitHub

Java extension and bindings for PDAL

Scala versions: 2.12 2.13 3.x

PDAL Java bindings

CI Join the chat at https://gitter.im/PDAL/PDAL Maven Central Snapshots

Java bindings to use PDAL on JVM (supports PDAL >= 2.0). Mac users can experience some issues with bindings that were build against a different PDAL version, so try to use a consistent PDAL version.

It is released independently from PDAL itself as of PDAL 1.7.

See https://pdal.io/java.html for more info.

Using PDAL JNI with SBT

// pdal is published to maven central, but you can use the following repos in addition
resolvers ++= 
  Resolver.sonatypeOssRepos("releases") ++ 
  Resolver.sonatypeOssRepos("snapshots") // for snaphots

// `<latest version>` refers to the version indicated by the badge above
libraryDependencies ++= Seq(
  "io.pdal" %% "pdal" % "<latest version>", // core library
  "io.pdal" %  "pdal-native" % "<latest version>" // jni bindings

If you would like to use your own bindings, it is necessary to set java.library.path:

// Mac OS X example with manual JNI installation
// cp -f native/target/resource_managed/main/native/x86_64-darwin/libpdaljni.2.1.dylib /usr/local/lib/libpdaljni.2.1.dylib
// place built binary into /usr/local/lib, and pass java.library.path to your JVM
javaOptions += "-Djava.library.path=/usr/local/lib"

You can use pdal-native dep in case you don't have installed JNI bindings and to avoid steps described above. Dependency contains bindings for x86_64-darwin and x86_64-linux, other versions are not supported yet.

PDAL-Scala (Scala 2.x)

Scala API allows to build pipeline expressions instead of writing a raw JSON.

// `<latest version>` refers to the version indicated by the badge above
libraryDependencies ++= Seq(
  "io.pdal" %% "pdal-scala" % "<latest version>", // scala core library
  "io.pdal" %  "pdal-native" % "<latest version>" // jni bindings

Scala API covers PDAL 2.0.x, to use any custom DSL that is not covered by the current Scala API you can use RawExpr type to build Pipeline Expression.

Code examples

// To construct the expected json
val expected =
     |  "pipeline" : [
     |    {
     |      "filename" : "/path/to/las",
     |      "type" : "readers.las"
     |    },
     |    {
     |      "type" : "filters.crop"
     |    },
     |    {
     |      "filename" : "/path/to/new/las",
     |      "type" : "writers.las"
     |    }
     |  ]
// The same, but using scala DSL
val pc = ReadLas("/path/to/las") ~ FilterCrop() ~ WriteLas("/path/to/new/las")

// The same, but using RawExpr, to support not implemented PDAL Pipeline API features
// RawExpr accepts a circe.Json type, which can be a json object of any desired complexity
val pcWithRawExpr = ReadLas("/path/to/las") ~ RawExpr(Map("type" -> "filters.crop").asJson) ~ WriteLas("/path/to/new/las") 

Demo project example

JNI bindings basic usage examples can be found here.

How to compile

Development purposes (including binaries) compilation:

  1. Install PDAL (using brew / package managers (unix) / build from sources / etc)
  2. Build native libs ./sbt native/nativeCompile (optionally, binaries would be built during tests run)
  3. Run ./sbt core/test to run PDAL tests

Only Java development purposes compilation:

  2. If you don't want to provide global variable you can pass -Djava.library.path=<path> into sbt: ./sbt -Djava.library.path=<path>
  3. Set PDAL_DEPEND_ON_NATIVE=false (to disable native project build)
  4. Run PDAL_DEPEND_ON_NATIVE=false ./sbt

Finally the possible command to launch and build PDAL JNI bindings could be:

# Including binaries build
# Java side development without binaries build
PDAL_DEPEND_ON_NATIVE=false ./sbt -Djava.library.path=<path>

Possible issues and solutions

  1. In case of not installed as global PDAL change this line to:

In this case sbt launch would be the following:

PDAL_LD_FLAGS=`pdal-config --libs` PDAL_CXX_FLAGS=`pdal-config --includes` ./sbt
  1. Sometimes can happen a bad dynamic linking issue (somehow spoiled environment), the quick workaround would be to replace this line to:
set(CMAKE_CXX_FLAGS "-L<path to dynamic libs> -std=c++11")

How to release

All the instructions related to the local / maven release process are documented in the HOWTORELEASE.txt file.

For the local publish it is possible to use the following commands:

  • scripts/publish-local.sh - to publish Scala artifacts
  • scripts/publish-local-native.sh - to compile and publish artifact with native binaries

For the additional information checkout the HOWTORELEASE.txt file and the scripts directory.