> **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](https://csiro-robotics.github.io/Wild-Places/#8-Download)

## 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](https://github.com/astral-sh/uv) or pip to install dependencies:

```bash
uv pip install -e .
```

Or use pip directly:

```bash
pip install wild-dataloader
```

## Quick Start

```python
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:
   ```bash
   cd example/cpp
   cmake -S . -B build
   cmake --build build
   ```
4. Run the example:
   ```bash
   ./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  
  ```cpp
  #include <pybind11/embed.h>
  namespace py = pybind11;
  py::scoped_interpreter guard{};
  ```
- Import `wild_dataloader` module  
  ```cpp
  py::module_ kd = py::module_::import("wild_dataloader");
  py::object PointCloudLoader = kd.attr("PointCloudLoader");
  py::object FrameID = kd.attr("FrameID");
  ```
- Create `PointCloudLoader` instance  
  ```cpp
  const char* root = "/ws/data/wild/Karawatha/K-01";
  py::object loader =
    PointCloudLoader(root, py::arg("frame_id") = FrameID.attr("WORLD"));
  ```
- Read dataset length  
  ```cpp
  std::size_t n = loader.attr("__len__")().cast<std::size_t>();
  std::cout << "dataset length = " << n << "\n";
  ```
- Read point cloud and pose, print shape  
  ```cpp
  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)  
  ```cpp
  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:

```python
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:

```bash
uv pip install .[dev]
uv run pytest
```

## Changelog

- **v0.1.0**: Initial version with basic functionality
