Skip to content

Commit 25dd25b

Browse files
WhiteSteWhiteSte
authored
Refactor the readme file (#81)
* Update README.md * Refactor of the readme file
1 parent e825816 commit 25dd25b

File tree

1 file changed

+93
-82
lines changed

1 file changed

+93
-82
lines changed

‎README.md‎

Lines changed: 93 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,32 @@
1-
# PDAL Java bindings
1+
# PDAL Java Bindings
22

33
[![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/)
44

5-
Java bindings to use PDAL on JVM (supports PDAL >= 2.0).
6-
Mac users can experience some issues with bindings that were build against a different PDAL version,
7-
so try to use a consistent PDAL version.
5+
6+
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.
87

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

11-
See [https://pdal.io/java.html](https://pdal.io/java.html) for more info.
10+
See [https://pdal.io/java.html](https://pdal.io/java.html) for more info.
11+
1212

13-
## Using PDAL JNI with SBT
13+
## Table of Contents
14+
- [Usage](#usage)
15+
- [Examples](#examples)
16+
- [Build](#build)
17+
- [Possible issues and solutions](#possible-issues-and-solutions)
18+
- [How To Release](#how-to-release)
19+
20+
## Usage
21+
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.
22+
Dependency contains bindings for `x86_64-darwin` and `x86_64-linux`, other versions are not supported yet.
1423

24+
### Using PDAL JNI With SBT
1525
```scala
1626
// pdal is published to maven central, but you can use the following repos in addition
17-
resolvers ++=
18-
Resolver.sonatypeOssRepos("releases") ++
27+
resolvers ++=
28+
Resolver.sonatypeOssRepos("releases") ++
1929
Resolver.sonatypeOssRepos("snapshots") // for snaphots
20-
2130
// `<latest version>` refers to the version indicated by the badge above
2231
libraryDependencies ++= Seq(
2332
"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
3443
javaOptions += "-Djava.library.path=/usr/local/lib"
3544
```
3645

37-
You can use `pdal-native` dep in case you don't have installed JNI bindings and to avoid steps described above.
38-
Dependency contains bindings for `x86_64-darwin` and `x86_64-linux`, other versions are not supported yet.
39-
40-
## PDAL-Scala (Scala 2.x)
4146

47+
### PDAL-Scala (Scala 2.x)
4248
Scala API allows to build pipeline expressions instead of writing a raw JSON.
4349

4450
```scala
@@ -49,17 +55,16 @@ libraryDependencies ++= Seq(
4955
)
5056
```
5157

52-
Scala API covers PDAL 2.0.x, to use any custom DSL that is not covered by the
58+
Scala API covers PDAL 2.0.x, to use any custom DSL that is not covered by the
5359
current Scala API you can use `RawExpr` type to build `Pipeline Expression`.
5460

55-
## Code examples
5661

62+
## Examples
5763
#### Demo project with examples
5864

5965
JNI bindings basic usage examples can be found [here](./examples).
6066

6167
### PDAL Core (Scala 2.x / 3.x)
62-
6368
```scala
6469
import io.pdal._
6570

@@ -119,24 +124,24 @@ import io.pdal.*;
119124
// pipeline definition
120125
String json =
121126
"""
122-
|{
123-
| "pipeline" : [
124-
| {
125-
| "filename" : "/path/to/las",
126-
| "type" : "readers.las"
127-
| },
128-
| {
129-
| "type" : "filters.crop"
130-
| },
131-
| {
132-
| "filename" : "/path/to/new/las",
133-
| "type" : "writers.las"
134-
| }
135-
| ]
136-
|}
127+
|{
128+
| "pipeline" : [
129+
| {
130+
| "filename" : "/path/to/las",
131+
| "type" : "readers.las"
132+
| },
133+
| {
134+
| "type" : "filters.crop"
135+
| },
136+
| {
137+
| "filename" : "/path/to/new/las",
138+
| "type" : "writers.las"
139+
| }
140+
| ]
141+
|}
137142
""";
138143
139-
var pipeline = new Pipeline(json, LogLevel.Error());
144+
var pipeline = new Pipeline(json, LogLevel.Error());
140145
141146
pipeline.initialize(); // initialize the pipeline
142147
pipeline.execute(); // execute the pipeline
@@ -174,89 +179,95 @@ import io.pdal.pipeline._
174179
175180
// To construct the expected json
176181
val expected =
177-
"""
178-
|{
179-
| "pipeline" : [
180-
| {
181-
| "filename" : "/path/to/las",
182-
| "type" : "readers.las"
183-
| },
184-
| {
185-
| "type" : "filters.crop"
186-
| },
187-
| {
188-
| "filename" : "/path/to/new/las",
189-
| "type" : "writers.las"
190-
| }
191-
| ]
192-
|}
182+
"""
183+
|{
184+
| "pipeline" : [
185+
| {
186+
| "filename" : "/path/to/las",
187+
| "type" : "readers.las"
188+
| },
189+
| {
190+
| "type" : "filters.crop"
191+
| },
192+
| {
193+
| "filename" : "/path/to/new/las",
194+
| "type" : "writers.las"
195+
| }
196+
| ]
197+
|}
193198
""".stripMargin
194-
195199
// The same, but using scala DSL
196200
val pc = ReadLas("/path/to/las") ~ FilterCrop() ~ WriteLas("/path/to/new/las")
197201

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

202206
// Create Pipelines from the constructed expressions
203207
val pipelinePc = pc.toPipeline
204208
val pipelinePc = pcWithRawExpr.toPipline
205209
```
206210

207-
## How to compile
208-
211+
## Build
209212
Development purposes (including binaries) compilation:
210-
1. Install PDAL (using brew / package managers (unix) / build from sources / etc)
211-
2. Build native libs `./sbt native/nativeCompile` (optionally, binaries would be built during tests run)
212-
3. Run `./sbt core/test` to run PDAL tests
213+
1. Install PDAL (using brew / package managers (unix) / build from sources / [Conda](#install-pdal-with-conda) / etc)
214+
2. Install sbt (using brew / package managers (unix)) (only after `v2.4.x`)
215+
3. Build native libs `sbt native/nativeCompile` (optionally, binaries would be built during tests run) or `sbt native/publishLocal` for the built jar only
216+
4. Run `sbt core/test` to run PDAL tests
213217

214-
Only Java development purposes compilation:
215-
1. Provide `$LD_LIBRARY_PATH` or `$DYLD_LIBRARY_PATH`
216-
2. If you don't want to provide global variable you can pass `-Djava.library.path=<path>` into sbt:
217-
`./sbt -Djava.library.path=<path>`
218-
3. Set `PDAL_DEPEND_ON_NATIVE=false` (to disable `native` project build)
219-
4. Run `PDAL_DEPEND_ON_NATIVE=false ./sbt`
220218

219+
Only Java development purposes compilation:
220+
1. Provide `$LD_LIBRARY_PATH` or `$DYLD_LIBRARY_PATH`
221+
2. If you don't want to provide global variable you can pass `-Djava.library.path=<path>` into sbt:
222+
`./sbt -Djava.library.path=<path>`
223+
3. Set `PDAL_DEPEND_ON_NATIVE=false` (to disable `native` project build)
224+
4. Run `PDAL_DEPEND_ON_NATIVE=false sbt`
221225
Finally the possible command to launch and build PDAL JNI bindings could be:
222-
223226
```bash
224227
# Including binaries build
225-
./sbt
228+
sbt
226229
```
227-
228230
```bash
229231
# Java side development without binaries build
230-
PDAL_DEPEND_ON_NATIVE=false ./sbt -Djava.library.path=<path>
232+
PDAL_DEPEND_ON_NATIVE=false sbt -Djava.library.path=<path>
231233
```
234+
#### Mac-OS ARM
235+
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.
232236

233-
### Possible issues and solutions
237+
## Possible issues and solutions
234238

235-
1. In case of not installed as global PDAL change [this](./java/native/src/CMakeLists.txt#L25) line to:
239+
#### - In case of not installed as global PDAL change [this](./java/native/src/CMakeLists.txt#L25) line to:
240+
```cmake
241+
set(CMAKE_CXX_FLAGS "$ENV{PDAL_LD_FLAGS} $ENV{PDAL_CXX_FLAGS} -std=c++11")
242+
```
243+
In this case sbt launch would be the following:
244+
```bash
245+
PDAL_LD_FLAGS=`pdal-config --libs` PDAL_CXX_FLAGS=`pdal-config --includes` sbt
246+
```
247+
248+
#### - Sometimes can happen a bad dynamic linking issue (somehow spoiled environment),
236249

237-
```cmake
238-
set(CMAKE_CXX_FLAGS "$ENV{PDAL_LD_FLAGS} $ENV{PDAL_CXX_FLAGS} -std=c++11")
239-
```
240-
In this case sbt launch would be the following:
250+
the quick workaround would be to replace [this](./java/native/src/CMakeLists.txt#L25) line to:
241251

242-
```bash
243-
PDAL_LD_FLAGS=`pdal-config --libs` PDAL_CXX_FLAGS=`pdal-config --includes` ./sbt
244-
```
252+
```cmake
253+
set(CMAKE_CXX_FLAGS "-L<path to dynamic libs> -std=c++11")
254+
```
245255

246-
2. Sometimes can happen a bad dynamic linking issue (somehow spoiled environment),
247-
the quick workaround would be to replace [this](./java/native/src/CMakeLists.txt#L25) line to:
256+
#### - On mac os could be difficult to install PDAL sometimes (near new releases). You have three options
257+
- ##### Install PDAL with conda
258+
Here the [PDAL conda guide](https://pdal.io/en/2.6.0/workshop/conda.html)
248259

249-
```cmake
250-
set(CMAKE_CXX_FLAGS "-L<path to dynamic libs> -std=c++11")
251-
```
260+
- ##### Install PDAL with brew
261+
Just run `brew install pdal`
252262

253-
## How to release
263+
- ##### Build PDAL from sources
264+
Follow the [official guide](https://pdal.io/en/latest/development/compilation/index.html#compilation)
254265

266+
## How To Release
255267
All the instructions related to the local / maven release process are documented in the [HOWTORELEASE.txt](./HOWTORELEASE.txt) file.
256268

257269
For the local publish it is possible to use the following commands:
258-
259270
* `scripts/publish-local.sh` - to publish Scala artifacts
260271
* `scripts/publish-local-native.sh` - to compile and publish artifact with native binaries
261-
262272
For the additional information checkout the [HOWTORELEASE.txt](./HOWTORELEASE.txt) file and the [scripts](./scripts) directory.
273+

0 commit comments

Comments
 (0)