diff --git a/README.md b/README.md index da4c106..9d3caf0 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,32 @@ -# PDAL Java bindings +# PDAL Java Bindings [![CI](https://github.com/PDAL/java/workflows/CI/badge.svg)](https://github.com/PDAL/java/actions) [![Join the chat at https://gitter.im/PDAL/PDAL](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/PDAL/PDAL?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Maven Central](https://img.shields.io/maven-central/v/io.pdal/pdal_2.13)](https://search.maven.org/search?q=g:io.pdal) [![Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/io.pdal/pdal_2.13)](https://oss.sonatype.org/content/repositories/snapshots/io/pdal/) -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. + +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](https://pdal.io/java.html) for more info. + See [https://pdal.io/java.html](https://pdal.io/java.html) for more info. + -## Using PDAL JNI with SBT +## Table of Contents +- [Usage](#usage) +- [Examples](#examples) +- [Build](#build) +- [Possible issues and solutions](#possible-issues-and-solutions) +- [How To Release](#how-to-release) + +## Usage +You can use `pdal-native` dep published into maven central in case you don't have installed JNI bindings and to avoid steps described below. +Dependency contains bindings for `x86_64-darwin` and `x86_64-linux`, other versions are not supported yet. +### Using PDAL JNI With SBT ```scala // pdal is published to maven central, but you can use the following repos in addition -resolvers ++= - Resolver.sonatypeOssRepos("releases") ++ +resolvers ++= + Resolver.sonatypeOssRepos("releases") ++ Resolver.sonatypeOssRepos("snapshots") // for snaphots - // `` refers to the version indicated by the badge above libraryDependencies ++= Seq( "io.pdal" %% "pdal" % "", // core library @@ -34,11 +43,8 @@ If you would like to use your own bindings, it is necessary to set `java.library 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) +### PDAL-Scala (Scala 2.x) Scala API allows to build pipeline expressions instead of writing a raw JSON. ```scala @@ -49,17 +55,16 @@ libraryDependencies ++= Seq( ) ``` -Scala API covers PDAL 2.0.x, to use any custom DSL that is not covered by the +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 +## Examples #### Demo project with examples JNI bindings basic usage examples can be found [here](./examples). ### PDAL Core (Scala 2.x / 3.x) - ```scala import io.pdal._ @@ -119,24 +124,24 @@ import io.pdal.*; // pipeline definition String json = """ - |{ - | "pipeline" : [ - | { - | "filename" : "/path/to/las", - | "type" : "readers.las" - | }, - | { - | "type" : "filters.crop" - | }, - | { - | "filename" : "/path/to/new/las", - | "type" : "writers.las" - | } - | ] - |} + |{ + | "pipeline" : [ + | { + | "filename" : "/path/to/las", + | "type" : "readers.las" + | }, + | { + | "type" : "filters.crop" + | }, + | { + | "filename" : "/path/to/new/las", + | "type" : "writers.las" + | } + | ] + |} """; -var pipeline = new Pipeline(json, LogLevel.Error()); +var pipeline = new Pipeline(json, LogLevel.Error()); pipeline.initialize(); // initialize the pipeline pipeline.execute(); // execute the pipeline @@ -174,89 +179,95 @@ import io.pdal.pipeline._ // 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" - | } - | ] - |} + """ + |{ + | "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") +val pcWithRawExpr = ReadLas("/path/to/las") ~ RawExpr(Map("type" -> "filters.crop").asJson) ~ WriteLas("/path/to/new/las") // Create Pipelines from the constructed expressions val pipelinePc = pc.toPipeline val pipelinePc = pcWithRawExpr.toPipline ``` -## How to compile - +## Build 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 +1. Install PDAL (using brew / package managers (unix) / build from sources / [Conda](#install-pdal-with-conda) / etc) +2. Install sbt (using brew / package managers (unix)) (only after `v2.4.x`) +3. Build native libs `sbt native/nativeCompile` (optionally, binaries would be built during tests run) or `sbt native/publishLocal` for the built jar only +4. 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=` into sbt: - `./sbt -Djava.library.path=` - 3. Set `PDAL_DEPEND_ON_NATIVE=false` (to disable `native` project build) - 4. Run `PDAL_DEPEND_ON_NATIVE=false ./sbt` +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=` into sbt: +`./sbt -Djava.library.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: - ```bash # Including binaries build -./sbt +sbt ``` - ```bash # Java side development without binaries build -PDAL_DEPEND_ON_NATIVE=false ./sbt -Djava.library.path= +PDAL_DEPEND_ON_NATIVE=false sbt -Djava.library.path= ``` +#### Mac-OS ARM +Natives for arm64 are still not pre-built. If you need to get them, follow the guide above for a self build and finally go to `../pdal-java/native/target/`, here you will find the built `pdal-native.jar`. If you want to use it in a Java project, for example, you can go to `./m2/repository/io/pdal/pdal-native//` and replace the one taken from Maven with the one you have just built. -### Possible issues and solutions +## Possible issues and solutions -1. In case of not installed as global PDAL change [this](./java/native/src/CMakeLists.txt#L25) line to: +#### - In case of not installed as global PDAL change [this](./java/native/src/CMakeLists.txt#L25) line to: +```cmake +set(CMAKE_CXX_FLAGS "$ENV{PDAL_LD_FLAGS} $ENV{PDAL_CXX_FLAGS} -std=c++11") +``` +In this case sbt launch would be the following: +```bash +PDAL_LD_FLAGS=`pdal-config --libs` PDAL_CXX_FLAGS=`pdal-config --includes` sbt +``` + +#### - Sometimes can happen a bad dynamic linking issue (somehow spoiled environment), - ```cmake - set(CMAKE_CXX_FLAGS "$ENV{PDAL_LD_FLAGS} $ENV{PDAL_CXX_FLAGS} -std=c++11") - ``` - In this case sbt launch would be the following: +the quick workaround would be to replace [this](./java/native/src/CMakeLists.txt#L25) line to: - ```bash - PDAL_LD_FLAGS=`pdal-config --libs` PDAL_CXX_FLAGS=`pdal-config --includes` ./sbt - ``` +```cmake +set(CMAKE_CXX_FLAGS "-L -std=c++11") +``` -2. Sometimes can happen a bad dynamic linking issue (somehow spoiled environment), - the quick workaround would be to replace [this](./java/native/src/CMakeLists.txt#L25) line to: +#### - On mac os could be difficult to install PDAL sometimes (near new releases). You have three options +- ##### Install PDAL with conda + Here the [PDAL conda guide](https://pdal.io/en/2.6.0/workshop/conda.html) - ```cmake - set(CMAKE_CXX_FLAGS "-L -std=c++11") - ``` +- ##### Install PDAL with brew + Just run `brew install pdal` -## How to release +- ##### Build PDAL from sources + Follow the [official guide](https://pdal.io/en/latest/development/compilation/index.html#compilation) +## How To Release All the instructions related to the local / maven release process are documented in the [HOWTORELEASE.txt](./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](./HOWTORELEASE.txt) file and the [scripts](./scripts) directory. +