Skip to content

Commit

Permalink
Expand Code examples README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
pomadchin committed Jan 19, 2024
1 parent 5b00174 commit 3b85352
Show file tree
Hide file tree
Showing 2 changed files with 134 additions and 32 deletions.
128 changes: 100 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,18 @@ libraryDependencies ++= Seq(
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
## Code examples

#### Demo project with examples

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

### PDAL Core (Scala 2.x / 3.x)

```scala
// To construct the expected json
val expected =
import io.pdal._

val json =
"""
|{
| "pipeline" : [
Expand All @@ -74,18 +81,43 @@ val expected =
| ]
|}
""".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 pipeline = Pipeline(json)
pipeline.validate() // check if our JSON and options were good
pipeline.setLogLevel(8) // make it really noisy
pipeline.execute() // execute the pipeline
val metadata = pipeline.getMetadata() // retrieve metadata
val pvs = pipeline.getPointViews() // iterator over PointViews
val pv = pvs.next() // let's take the first PointView

// load all points into JVM memory
// PointCloud provides operations on PDAL points that
// are loaded in this case into JVM memory as a single Array[Byte]
val pointCloud = pv.getPointCloud()
val x = pointCloud.getDouble(0, DimType.X) // get a point with PointId = 0 and only a single dimensions

// in some cases it is not neccesary to load everything into JVM memory
// so it is possible to get only required points directly from the PointView
val y = pv.getDouble(0, DimType.Y)

// it is also possible to get access to the triangular mesh generated via PDAL
val mesh = pv.getTriangularMesh()
// the output is an Array of Triangles
// Each Triangle contains PointIds from the PDAL point table
val triangles: Array[Triangle] = mesh.asArray

pv.close()
pvs.close()
pipeline.close()
```
## Use PDAL inside a JAVA environment
This is an example about how to use pdal inside a pure java environment.

### PDAL Core (Java)

```java
import io.pdal.DimType;
import io.pdal.LogLevel;
import io.pdal.Pipeline;

// Create the expected json String
String expectedJSON =
"""
Expand All @@ -104,32 +136,72 @@ String expectedJSON =
| }
| ]
|}
"""
// Decide the verbosity of your output
int logLevel = 0;
""";
var pipeline = new Pipeline(json, LogLevel.Error());
pipeline.initialize(); // initialize the pipeline
pipeline.execute(); // execute the pipeline
var metadata = pipeline.getMetadata(); // retrieve metadata
var pvs = pipeline.getPointViews(); // iterator over PointViews
var pv = pvs.next(); // let's take the first PointView
// Initialine a Pipeline object
// Be careful, before version v2.5.0 the constructor was 'new Pipeline(String jsonString)'
Pipeline pipeline = new Pipeline(json,3);
// load all points into JVM memory
// PointCloud provides operations on PDAL points that
// are loaded in this case into JVM memory as a single Array[Byte]
var pointCloud = pv.getPointCloud();
var x = pointCloud.getDouble(0, DimType.X()); // get a point with PointId = 0 and only a single dimensions
// Initialize the pipeline
pipeline.initialize();
// in some cases it is not neccesary to load everything into JVM memory
// so it is possible to get only required points directly from the PointView
var y = pv.getDouble(0, DimType.Y());
// Execute the pipeline
pipeline.execute();
// it is also possible to get access to the triangular mesh generated via PDAL
var mesh = pv.getTriangularMesh();
// the output is an Array of Triangles
// Each Triangle contains PointIds from the PDAL point table
var triangles = mesh.asArray();
// Now you can for example extract a PointViewIterator
PointViewIterator pvs = pipeline.getPointViews();
// And a single PointView..
PointView pv = pvs.next();
// Now remember to close the pipeline to avoid a leak of resources
pv.close();
pvs.close();
pipeline.close();
```
### Demo project example
### PDAL Scala
JNI bindings basic usage examples can be found [here](./examples).
```scala
// 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")

// Create Pipelines from the constructed expressions
val pipelinePc = pc.toPipeline
val pipelinePc = pcWithRawExpr.toPipline
```

## How to compile

Expand Down
38 changes: 34 additions & 4 deletions examples/pdal-jni/src/main/java/com/azavea/MainJava.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package com.azavea;

import io.pdal.DimType;
import io.pdal.LogLevel;
import io.pdal.Pipeline;

Expand All @@ -9,11 +10,40 @@ class MainJava {

public static void main(String[] args) {
// can be replaced via io.pdal.Pipeline$.MODULE$.apply(json, LogLevel.Error());
// which incapsulates initialize() call
// which encapsulates initialize() call
// var pipeline = new Pipeline(json, LogLevel.Error());
// pipeline.initialize();
// pipeline.execute();
// System.out.println("pipeline.getMetadata():" + pipeline.getMetadata());
// pipeline.close();

var pipeline = new Pipeline(json, LogLevel.Error());
pipeline.initialize();
pipeline.execute();
System.out.println("pipeline.getMetadata():" + pipeline.getMetadata());

pipeline.initialize(); // initialize the pipeline
pipeline.execute(); // execute the pipeline

var metadata = pipeline.getMetadata(); // retrieve metadata
var pvs = pipeline.getPointViews(); // iterator over PointViews
var pv = pvs.next(); // let's take the first PointView

// load all points into JVM memory
// PointCloud provides operations on PDAL points that
// are loaded in this case into JVM memory as a single Array[Byte]
var pointCloud = pv.getPointCloud();
var x = pointCloud.getDouble(0, DimType.X()); // get a point with PointId = 0 and only a single dimensions

// in some cases it is not neccesary to load everything into JVM memory
// so it is possible to get only required points directly from the PointView
var y = pv.getDouble(0, DimType.Y());

// it is also possible to get access to the triangular mesh generated via PDAL
var mesh = pv.getTriangularMesh();
// the output is an Array of Triangles
// Each Triangle contains PointIds from the PDAL point table
var triangles = mesh.asArray();

pv.close();
pvs.close();
pipeline.close();
}
}

0 comments on commit 3b85352

Please sign in to comment.