https://github.com/rockrobotic/copc-lib
copc-lib provides an easy-to-use reader and writer interface for creating and reading Cloud Optimized Point Clouds, with bindings for Python and C++
https://github.com/rockrobotic/copc-lib
copc cpp las laz point-cloud python spatial
Last synced: 12 days ago
JSON representation
copc-lib provides an easy-to-use reader and writer interface for creating and reading Cloud Optimized Point Clouds, with bindings for Python and C++
- Host: GitHub
- URL: https://github.com/rockrobotic/copc-lib
- Owner: RockRobotic
- License: other
- Created: 2021-08-23T15:41:05.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-02-04T00:43:18.000Z (3 months ago)
- Last Synced: 2025-04-12T19:17:17.878Z (12 days ago)
- Topics: copc, cpp, las, laz, point-cloud, python, spatial
- Language: C++
- Homepage:
- Size: 710 KB
- Stars: 49
- Watchers: 8
- Forks: 15
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# copc-lib
copc-lib provides an easy-to-use reader and writer interface for [COPC](https://copc.io/) point clouds, with bindings for python and C++.
## Installation
The quickest way to get started with copc-lib is with our conda and pip packages.
### Conda
Conda includes both the C++ and python bindings:
```bash
conda install -c conda-forge copc-lib
```
### Pip
Pip provide only python bindings:
```bash
pip install copclib
```
### Building from source
#### Dependencies
copc-lib has the following dependencies:
- laz-perf>=[3.0.0](https://github.com/hobu/laz-perf/releases/tag/3.0.0)
- Catch2 v2.x (test suite only)
- Pybind11 (python bindings only)
To install all dependencies:
```bash
conda install -c conda-forge "laz-perf>=3.0" Catch2=2.13 pybind11
```
#### C++
```bash
git clone https://github.com/RockRobotic/copc-lib.git
cd copc-lib
mkdir build && cd build
cmake ..
cmake --build .
sudo cmake --install .
```
#### Python
```bash
git clone https://github.com/RockRobotic/copc-lib.git
pip install ./copc-lib
```
#### Example Files & Unit Tests
To build the copc-lib examples and unit tests along with the main library, you must enable them:
```bash
mkdir build && cd build
cmake .. -DWITH_TESTS=ON -DWITH_PYTHON=ON
cmake --build .
ctest # All tests should pass
```
## Usage
The `Reader` and `Writer` objects provide the primary means of interfacing with your COPC files. For more complex use cases, we also provide additional objects such as LAZ Compressors and Decompressors (see [example/example-writer.cpp](example/example-writer.cpp)).
For common use cases, see the `example` and `test` folders for full examples.
### C++
copc-lib is compatible with CMake. Assuming copc-lib and lazperf are installed on the system, you can link with them in your `CMakeLists.txt`:
```CMake
find_package(COPCLIB REQUIRED)
find_package(LAZPERF REQUIRED)
add_executable(funlib fun-main.cpp)
target_link_libraries(funlib COPCLIB::copc-lib LAZPERF::lazperf)
```
The primary public interface will be your [FileReader](./cpp/include/copc-lib/io/copc_reader.hpp) and [FileWriter](./cpp/include/copc-lib/io/copc_writer.hpp) objects. Check the headers and [example files](./example) for documentation.
```cpp
#include
#include
void main()
{
// Create a reader object
FileReader reader("autzen-classified.copc.laz");
// Get the node metadata from the hierarchy
auto node = reader.FindNode(copc.VoxelKey(0, 0, 0, 0));
// Fetch the points of a node
auto points = reader.GetPoints(node);
// Iterate through each point
for (const auto &point : points)
std::cout << "X: " << point.X ", Y: " << point.Y << ", Z: " << point.Z << std::endl;
}
```
### Python
[Example files](./example) are also provided for python.
```python
import copclib as copc
# Create a reader object
reader = copc.FileReader("autzen-classified.copc.laz")
# Get the node metadata from the hierarchy
node = reader.FindNode(copc.VoxelKey(0, 0, 0, 0))
# Fetch the points of a node
points = reader.GetPoints(node)
# Iterate through each point
for point in points:
print(point.x, point.y, point.z)
```
Note that, in python, dimension names for points follow the [laspy naming scheme](https://laspy.readthedocs.io/en/latest/intro.html#point-format-6), with the exception of `scan_angle`.
## Helpful Links
- [COPC Spec](https://copc.io/)
- [copc.js](https://github.com/connormanning/copc.js) - TypeScript library for reading COPC files
- [copc.js for browser](https://github.com/connormanning/copc.js/pull/1) - Webpacked version of copc.js for the browser
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
## License
Please see [LICENSE.md](LICENSE.md)
## Credits
copc-lib is created and maintained by [Chris Lee](https://github.com/CCInc), [Leo Stanislas](https://github.com/leo-stan) and other members of [RockRobotic](https://github.com/RockRobotic).
The [COPC file format](https://copc.io) is created and maintained by HOBU Inc.
Some code has been adopted from [PDAL](https://github.com/PDAL/PDAL) and [lazperf](https://github.com/hobu/laz-perf), both of which are maintained by HOBU Inc.