Version Matrix

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 following repos in addition
resolvers ++= Seq(
  Resolver.sonatypeRepo("releases"),
  Resolver.sonatypeRepo("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"
     |    }
     |  ]
     |}
  """.stripMargin
  
// 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:

  1. Provide $LD_LIBRARY_PATH or $DYLD_LIBRARY_PATH
  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
./sbt
# 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:
set(CMAKE_CXX_FLAGS "$ENV{PDAL_LD_FLAGS} $ENV{PDAL_CXX_FLAGS} -std=c++11")

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.