Repository navigation
Refactor the readme file #81
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
baa193d
Update README.md
WhiteSte 197c51d
Refactor of the readme file
WhiteSte ac6d5ed
Merge branch 'main' into pr/81
WhiteSte da666b7
Merge branch 'main' into pr/81
WhiteSte 4189d7a
update readme with @pomadchin hints
WhiteSte 36a8b2b
fix design/layout
WhiteSte ae5bd72
Another adjustment
WhiteSte File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,23 +1,32 @@ | ||
| # PDAL Java bindings | ||
| # PDAL Java Bindings | ||
|
|
||
| [](https://github.com/PDAL/java/actions) [](https://gitter.im/PDAL/PDAL?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://search.maven.org/search?q=g:io.pdal) [](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. | ||
|
WhiteSte marked this conversation as resolved.
Resolved
|
||
|
|
||
| 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 | ||
|
|
||
| // `<latest version>` refers to the version indicated by the badge above | ||
| libraryDependencies ++= Seq( | ||
| "io.pdal" %% "pdal" % "<latest version>", // 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( | |
| ) | ||
| ``` | ||
|
|
||
|
WhiteSte marked this conversation as resolved.
Resolved
|
||
| 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 | ||
|
|
||
|
WhiteSte marked this conversation as resolved.
Resolved
|
||
| JNI bindings basic usage examples can be found [here](./examples). | ||
|
|
||
| ### PDAL Core (Scala 2.x / 3.x) | ||
|
|
||
| ```scala | ||
| import io.pdal._ | ||
|
|
||
|
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why these are gone? The original formatting was intentional.
Collaborator
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is this resolved? |
||
|
|
@@ -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 | ||
|
WhiteSte marked this conversation as resolved.
Resolved
|
||
|
|
||
| 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` | ||
|
|
||
| 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: | ||
|
|
||
| ```bash | ||
| # Including binaries build | ||
| ./sbt | ||
| sbt | ||
| ``` | ||
|
|
||
| ```bash | ||
| # Java side development without binaries build | ||
| PDAL_DEPEND_ON_NATIVE=false ./sbt -Djava.library.path=<path> | ||
| PDAL_DEPEND_ON_NATIVE=false sbt -Djava.library.path=<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/<your-version>/` 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<path to dynamic libs> -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<path to dynamic libs> -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. | ||
|
|
||
|
WhiteSte marked this conversation as resolved.
Resolved
|
||
| 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. | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.