wild-dataloader 0.1.1

Efficient and user-friendly point cloud data loader for the WILD Dataset, supporting multiple coordinate systems and numpy compatibility.

Note: This is an English translation of the original documentation in README_CN.md.

Wild-Places Point Cloud Data Loader

Easily read point cloud data and pose information from the Wild-Places dataset.

Dataset Homepage: Wild-Places Dataset

Project Overview

This project provides an efficient and user-friendly point cloud data loader for the Wild-Places dataset, supporting multiple coordinate system conversions, iteration, slicing, and more. It is suitable for autonomous driving, SLAM, 3D reconstruction, and similar scenarios.

Features

• Multiple Coordinate Systems Supported
  • BASE_LINK: Vehicle local coordinate system
  • WORLD: World coordinate system
• Iterator & Slicing: Supports iteration, slicing, and random access
• Numpy Compatible: Can read directly from numpy arrays
• Dataset Length: Supports the len() method

Installation

It is recommended to use uv or pip to install dependencies:

uv pip install -e .

Or use pip directly:

pip install wild-dataloader

Quick Start

from wild_dataloader import PointCloudLoader, FrameID

loader = PointCloudLoader("/path/to/wild/Karawatha")
pc, pose = loader[0]  # Read the first point cloud and its pose

# Iterate over the first 10 frames
for pc, pose in loader[:10]:
    # Process point cloud and pose
    pass

# Get dataset length
print(len(loader))

C++/pybind11 Example

This project supports direct invocation of the Python loader from C++ via pybind11, suitable for integration with C++ projects.
See example code in example/cpp/main.cc. Ensure the root path points to a valid Wild-Places dataset directory.

Build & Run Steps

1. Activate Python virtual environment (ensure wild-dataloader and pybind11 are installed)
2. Edit line 18 in main.cc to set the root variable to your dataset path, e.g. /ws/data/wild/Karawatha/K-01
3. Build the project:

   cd example/cpp
   cmake -S . -B build
   cmake --build build
   

4. Run the example:

   ./build/embed_loader
   

After running, it will print the dataset length, and the shapes of the point cloud and pose.

Main Code Logic

• Start Python interpreter

  #include <pybind11/embed.h>
  namespace py = pybind11;
  py::scoped_interpreter guard{};
  

• Import wild_dataloader module

  py::module_ kd = py::module_::import("wild_dataloader");
  py::object PointCloudLoader = kd.attr("PointCloudLoader");
  py::object FrameID = kd.attr("FrameID");
  

• Create PointCloudLoader instance

  const char* root = "/ws/data/wild/Karawatha/K-01";
  py::object loader =
    PointCloudLoader(root, py::arg("frame_id") = FrameID.attr("WORLD"));
  

• Read dataset length

  std::size_t n = loader.attr("__len__")().cast<std::size_t>();
  std::cout << "dataset length = " << n << "\n";
  

• Read point cloud and pose, print shape

  py::tuple item0 = loader[py::int_(0)];
  py::array_t<float> cld = item0[0].cast<py::array_t<float>>();
  py::array_t<double> pose = item0[1].cast<py::array_t<double>>();
  std::cout << "points shape = (" << cld.shape(0) << ", " << cld.shape(1) << ")\n";
  std::cout << "pose shape   = (" << pose.shape(0) << ", " << pose.shape(1) << ")\n";
  

• Iterate first 10 frames (optional)

  for (py::size_t i = 0; i < 10 && i < n; ++i) {
    py::tuple it = loader[py::int_(i)];
    // Process point cloud and pose here
  }
  

See example/cpp/main.cc for details.

Coordinate System Description

• BASE_LINK: LiDAR local coordinate system
• WORLD: World coordinate system

You can switch coordinate systems via the frame_id parameter or property:

loader.frame_id = FrameID.WORLD
pc, pose = loader[0]

API Description

• PointCloudLoader: Main loader class, supports indexing, slicing, iteration, etc.
• FrameID: Coordinate system enum type

Data Format

• Point cloud shape: [N, 3], representing [x, y, z]
• Pose matrix shape: [4, 4]

Dependencies

• numpy
• pypcd4
• scipy

Development/testing dependencies (see pyproject.toml):

• matplotlib
• pybind11
• pytest
• ipykernel
• ruff

Testing

Unit tests are included. Run:

uv pip install .[dev]
uv run pytest

Changelog

• v0.1.0: Initial version with basic functionality