{"id":19784481,"url":"https://github.com/pdal/java","last_synced_at":"2025-09-03T09:40:26.562Z","repository":{"id":41492010,"uuid":"125991459","full_name":"PDAL/java","owner":"PDAL","description":"Java extension and bindings for PDAL","archived":false,"fork":false,"pushed_at":"2024-10-28T03:43:21.000Z","size":1208,"stargazers_count":8,"open_issues_count":9,"forks_count":10,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-06T05:51:12.493Z","etag":null,"topics":["gis","hacktoberfest","java","jni","jni-bindings","pdal","pdal-jni","pointcloud","scala"],"latest_commit_sha":null,"homepage":"https://pdal.io/java.html","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PDAL.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-20T09:18:33.000Z","updated_at":"2024-12-16T13:49:53.000Z","dependencies_parsed_at":"2023-09-24T04:49:29.708Z","dependency_job_id":"db9be0a1-6244-4ad0-8c67-dd529146c8f4","html_url":"https://github.com/PDAL/java","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDAL%2Fjava","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDAL%2Fjava/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDAL%2Fjava/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PDAL%2Fjava/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PDAL","download_url":"https://codeload.github.com/PDAL/java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251791757,"owners_count":21644451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gis","hacktoberfest","java","jni","jni-bindings","pdal","pdal-jni","pointcloud","scala"],"created_at":"2024-11-12T06:11:37.347Z","updated_at":"2025-09-03T09:40:26.537Z","avatar_url":"https://github.com/PDAL.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PDAL Java Bindings\n\n[![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\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_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 Badge](https://img.shields.io/badge/snapshots-available-orange)](https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/io/pdal/pdal_3/) \n\nJava bindings to use PDAL on JVM (supports PDAL \u003e= 2.0). macOS users can experience some issues with bindings that were build against a different PDAL version, so try to use a consistent PDAL version. \n\nIt is released independently from PDAL itself as of PDAL 1.7.\n\n See [https://pdal.io/java.html](https://pdal.io/java.html) for more info.\n\n\n## Table of Contents\n- [Usage](#usage)\n- [Examples](#examples)\n- [Build](#build) \n- [Possible issues and solutions](#possible-issues-and-solutions)\n- [How To Release](#how-to-release)\n\n## Usage \nYou can use `pdal-native` dep published into maven central in case you don't have installed JNI bindings and to avoid steps described below.\nDependency contains bindings for `arm64-darwin`, and `x86_64-linux`, other versions are not supported yet. We dropped `x86_64-darwin` as of the PDAL Java `2.8.0` release.\n\n### Versioning scheme\n\nGiven a `{major}.{minor}.{patch}` version:\n* `{major}.{minor}` - matches the **PDAL** version it is published for\n  * e.g. **pdal-java** of version `2.6.1` is suitable for all **PDAL** versions `2.6.x` (`2.6.0`, ..., `2.6.3`, etc) major = `2`, minor = `6`\n* `{patch}` - this portion of the version corresponds to updates within **pdal-java** and should remain compatible with **PDAL library** `{major}.{minor}` versions\n  * This implies that there may be multiple **pdal-java** releases for the same **PDAL library** version. All releases are compatible with the matching **PDAL library** `{major}.{minor}` version. Thus, higher patch versions are to be preferred.\n\n### Using PDAL JNI With SBT\n```scala\n// pdal is published to maven central, the snapshot repository can be added in addition\nresolvers += Resolver.sonatypeCentralSnapshots // for snaphots\n// `\u003clatest version\u003e` refers to the version indicated by the badge above\nlibraryDependencies ++= Seq(\n  \"io.pdal\" %% \"pdal\" % \"\u003clatest version\u003e\", // core library\n  \"io.pdal\" %  \"pdal-native\" % \"\u003clatest version\u003e\" // jni bindings\n)\n```\n\nIf you would like to use your own bindings, it is necessary to set `java.library.path`:\n\n```scala\n// macOS X example with manual JNI installation\n// cp -f native/target/resource_managed/main/native/arm64-darwin/libpdaljni.2.8.dylib /usr/local/lib/libpdaljni.2.8.dylib\n// place built binary into /usr/local/lib, and pass java.library.path to your JVM\njavaOptions += \"-Djava.library.path=/usr/local/lib\"\n```\n\n\n### PDAL-Scala (Scala 2.x)\nScala API allows to build pipeline expressions instead of writing a raw JSON.\n\n```scala\n// `\u003clatest version\u003e` refers to the version indicated by the badge above\nlibraryDependencies ++= Seq(\n  \"io.pdal\" %% \"pdal-scala\" % \"\u003clatest version\u003e\", // scala core library\n  \"io.pdal\" %  \"pdal-native\" % \"\u003clatest version\u003e\" // jni bindings\n)\n```\n\nScala API covers PDAL 2.0.x, to use any custom DSL that is not covered by the\ncurrent Scala API you can use `RawExpr` type to build `Pipeline Expression`.\n\n\n## Examples\n#### Demo project with examples\n\nJNI bindings basic usage examples can be found [here](./examples).\n\n### PDAL Core (Scala 2.x / 3.x)\n```scala\nimport io.pdal._\n\n// pipeline definition\nval json =\n  \"\"\"\n     |{\n     |  \"pipeline\" : [\n     |    {\n     |      \"filename\" : \"/path/to/las\",\n     |      \"type\" : \"readers.las\"\n     |    },\n     |    {\n     |      \"type\" : \"filters.crop\"\n     |    },\n     |    {\n     |      \"filename\" : \"/path/to/new/las\",\n     |      \"type\" : \"writers.las\"\n     |    }\n     |  ]\n     |}\n  \"\"\".stripMargin\n\nval pipeline = Pipeline(json, LogLevel.Debug5) // initialize and make it really noisy\n\npipeline.execute() // execute the pipeline\n\nval metadata = pipeline.getMetadata() // retrieve metadata\nval pvs      = pipeline.getPointViews() // iterator over PointViews\nval pv       = pvs.next() // let's take the first PointView\n\n// load all points into JVM memory\n// PointCloud provides operations on PDAL points that\n// are loaded in this case into JVM memory as a single Array[Byte]\nval pointCloud = pv.getPointCloud()\nval x = pointCloud.getDouble(0, DimType.X) // get a point with PointId = 0 and only a single dimensions\n\n// in some cases it is not neccesary to load everything into JVM memory\n// so it is possible to get only required points directly from the PointView\nval y = pv.getDouble(0, DimType.Y)\n\n// it is also possible to get access to the triangular mesh generated via PDAL\nval mesh = pv.getTriangularMesh()\n// the output is an Array of Triangles\n// Each Triangle contains PointIds from the PDAL point table\nval triangles = mesh.asArray\n\npv.close()\npvs.close()\npipeline.close()\n```\n\n### PDAL Core (Java)\n\n```java\nimport io.pdal.*;\n\n// pipeline definition\nString json =\n  \"\"\"\n      {\n        \"pipeline\" : [\n          {\n            \"filename\" : \"/path/to/las\",\n            \"type\" : \"readers.las\"\n          },\n          {\n            \"type\" : \"filters.crop\"\n          },\n          {\n            \"filename\" : \"/path/to/new/las\",\n            \"type\" : \"writers.las\"\n          }\n        ]\n      }\n  \"\"\";\n\nvar pipeline = new Pipeline(json, LogLevel.Debug5()); // initialize and make it really noisy\n\npipeline.execute(); // execute the pipeline\n\nvar metadata = pipeline.getMetadata(); // retrieve metadata\nvar pvs      = pipeline.getPointViews(); // iterator over PointViews\nvar pv       = pvs.next(); // let's take the first PointView\n\n// load all points into JVM memory\n// PointCloud provides operations on PDAL points that\n// are loaded in this case into JVM memory as a single Array[Byte]\nvar pointCloud = pv.getPointCloud();\nvar x = pointCloud.getDouble(0, DimType.X()); // get a point with PointId = 0 and only a single dimensions\n\n// in some cases it is not neccesary to load everything into JVM memory\n// so it is possible to get only required points directly from the PointView\nvar y = pv.getDouble(0, DimType.Y());\n\n// it is also possible to get access to the triangular mesh generated via PDAL\nvar mesh = pv.getTriangularMesh();\n// the output is an Array of Triangles\n// Each Triangle contains PointIds from the PDAL point table\nvar triangles = mesh.asArray();\n\npv.close();\npvs.close();\npipeline.close();\n```\n\n### PDAL Scala\n\n```scala\nimport io.pdal._\nimport io.pdal.pipeline._\n\n// To construct the expected json\nval expected =\n  \"\"\" \n      |{\n      |  \"pipeline\" : [\n      |    {\n      |      \"filename\" : \"/path/to/las\",\n      |      \"type\" : \"readers.las\"\n      |    },\n      |    {\n      |      \"type\" : \"filters.crop\"\n      |    },\n      |    {\n      |      \"filename\" : \"/path/to/new/las\",\n      |      \"type\" : \"writers.las\"\n      |    }\n      |  ]\n      |}\n  \"\"\".stripMargin\n// The same, but using scala DSL\nval pc = ReadLas(\"/path/to/las\") ~ FilterCrop() ~ WriteLas(\"/path/to/new/las\")\n\n// The same, but using RawExpr, to support not implemented PDAL Pipeline API features\n// RawExpr accepts a circe.Json type, which can be a json object of any desired complexity\nval pcWithRawExpr = ReadLas(\"/path/to/las\") ~ RawExpr(Map(\"type\" -\u003e \"filters.crop\").asJson) ~ WriteLas(\"/path/to/new/las\")\n\n// Create Pipelines from the constructed expressions\nval pipeline = pc.toPipeline\nval pipelineRaw = pcWithRawExpr.toPipline\n```\n\n## Build\nDevelopment purposes (including binaries) compilation:\n1. Install PDAL (using brew / package managers (unix) / build from sources / [Conda](#install-pdal-with-conda) / etc) \n2. Install sbt (using brew / package managers (unix)) (only after `v2.4.x`)\n3. Build native libs `sbt native/nativeCompile` (optionally, binaries would be built during tests run) or `sbt native/publishLocal` for the built jar only\n4. Run `sbt core/test` to run PDAL tests\n\nOnly Java development purposes compilation:\n1. Provide `$LD_LIBRARY_PATH` or `$DYLD_FALLBACK_LIBRARY_PATH`\n2. If you don't want to provide global variable you can pass `-Djava.library.path=\u003cpath\u003e` into sbt:\n`./sbt -Djava.library.path=\u003cpath\u003e`\n3. Set `PDAL_DEPEND_ON_NATIVE=false` (to disable `native` project build)\n4. Run `PDAL_DEPEND_ON_NATIVE=false sbt`\nFinally the possible command to launch and build PDAL JNI bindings could be:\n```bash\n# Including binaries build\nsbt\n```\n```bash\n# Java side development without binaries build\nPDAL_DEPEND_ON_NATIVE=false sbt -Djava.library.path=\u003cpath\u003e\n```\n## Possible issues and solutions\n\n#### - In case of not installed as global PDAL change [this](./java/native/src/CMakeLists.txt#L25) line to:\n```cmake\nset(CMAKE_CXX_FLAGS \"$ENV{PDAL_LD_FLAGS} $ENV{PDAL_CXX_FLAGS} -std=c++11\")\n```\nIn this case sbt launch would be the following:\n```bash\nPDAL_LD_FLAGS=`pdal-config --libs` PDAL_CXX_FLAGS=`pdal-config --includes` sbt\n```\n\n#### - Sometimes can happen a bad dynamic linking issue (somehow spoiled environment),\n\nthe quick workaround would be to replace [this](./java/native/src/CMakeLists.txt#L25) line to:\n\n```cmake\nset(CMAKE_CXX_FLAGS \"-L\u003cpath to dynamic libs\u003e -std=c++11\")\n```\n\n#### - On macOS could be difficult to install PDAL sometimes (near new releases). You have three options\n- ##### Install PDAL with conda \n  Here the [PDAL conda guide](https://pdal.io/en/2.6.0/workshop/conda.html)\n\n- ##### Install PDAL with brew \n  Just run `brew install pdal`\n\n- ##### Build PDAL from sources \n  Follow the [official guide](https://pdal.io/en/latest/development/compilation/index.html#compilation)\n\n#### - When using the Maven Central JARs on macOS, I get `Library not loaded: @rpath/libpdalcpp.16.dylib` error\n\nIf you are sure PDAL is correctly installed, you can run `pdal-config --libs` and take the path after the `-L` argument\nand assign it to the `DYLD_FALLBACK_LIBRARY_PATH`:\n\n    ❯ pdal-config --libs\n    -L/opt/homebrew/Cellar/pdal/2.6.3/lib -lpdalcpp\n    ❯ export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/Cellar/pdal/2.6.3/lib\n    ❯ java -jar my-pdal-proj.jar\n\n## How To Release\nAll the instructions related to the local / maven release process are documented in the [HOWTORELEASE.txt](./HOWTORELEASE.txt) file.\n\nFor the local publish it is possible to use the following commands:\n* `scripts/publish-local.sh` - to publish Scala artifacts\n* `scripts/publish-local-native.sh` - to compile and publish artifact with native binaries\nFor the additional information checkout the [HOWTORELEASE.txt](./HOWTORELEASE.txt) file and the [scripts](./scripts) directory.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdal%2Fjava","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpdal%2Fjava","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdal%2Fjava/lists"}