Metadata-Version: 2.4
Name: highwayscene-proto
Version: 1.0.0
Summary: Reference Python reader and Protobuf schema for HighwayScene records
Author: Alexander Baumann
License-Expression: MIT
Project-URL: Homepage, https://highwayscene.github.io/
Project-URL: Dataset, https://huggingface.co/datasets/iis-esslingen/HighwayScene
Project-URL: Repository, https://github.com/HighwayScene/highwayscene-proto
Project-URL: Issues, https://github.com/HighwayScene/highwayscene-proto/issues
Keywords: lidar,point-cloud,protobuf,highwayscene,dataset
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: betterproto==1.2.5
Requires-Dist: numpy<3,>=1.24
Provides-Extra: visualization
Requires-Dist: open3d<1,>=0.18; extra == "visualization"
Provides-Extra: codegen
Requires-Dist: black==26.5.1; extra == "codegen"
Requires-Dist: betterproto[compiler]==1.2.5; extra == "codegen"
Requires-Dist: grpcio-tools==1.83.0; extra == "codegen"
Requires-Dist: protobuf==7.35.1; extra == "codegen"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.11; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Dynamic: license-file

# highwayscene-proto

`highwayscene-proto` is the reference Python reader and Protobuf schema for
[HighwayScene](https://huggingface.co/datasets/iis-esslingen/HighwayScene), a
multi-sensor static roadside LiDAR dataset. It provides generated message
classes, memory-efficient record iteration, random frame access, and typed
NumPy views of point-cloud channels.

HighwayScene accompanies the paper **“Beam-Wise Statistical Background
Subtraction for Static Roadside LiDAR: A Cross-Sensor Benchmark Study.”** See
the [project page](https://highwayscene.github.io/) for the paper, code,
dataset, and benchmark resources.

## Installation

Install the reader from PyPI:

```bash
python -m pip install highwayscene-proto
```

For development from a checkout:

```bash
python -m pip install -e '.[dev]'
```

Python 3.10 or newer is required.

## Quick start

Stream frames from a record without loading the complete file:

```python
from highwayscene import LaserName, decode_pointcloud, iter_frames

for frame in iter_frames("HighwayScene/test/record.pb"):
    print(frame.frame_id, frame.frame_timestamp_ns)
    for scan in frame.lidars:
        sensor = LaserName(scan.laser_name).name
        points = decode_pointcloud(scan.pointcloud)
        print(sensor, points.xyz.shape, points.channel_id)
```

Use `RecordFile` when you need indexed access:

```python
from highwayscene import RecordFile, decode_pointcloud

record = RecordFile("HighwayScene/test/record.pb")
frame = record[12]
xyz = decode_pointcloud(frame.lidars[0].pointcloud).xyz
```

The existing generated-module imports remain available:

```python
from highwayscene.frame import Frame
from highwayscene.sensors import LaserName, LidarScan
```

Imports through the former `a42` package name remain available as compatibility aliases.
New code should use the `highwayscene` namespace.

Inspect a file or a complete split from the command line:

```bash
highwayscene-inspect HighwayScene/test --limit 3
highwayscene-inspect HighwayScene/test/record.pb --json
```

## Dataset download and layout

Download HighwayScene with Git LFS or `huggingface_hub`:

```bash
python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='iis-esslingen/HighwayScene', repo_type='dataset', local_dir='HighwayScene')"
```

The point-cloud records are organized by benchmark split:

```text
HighwayScene/
├── train/*.pb
├── val/*.pb
├── test/*.pb
└── label/...
```

The labels under `label/` belong to the background-subtraction benchmark and
are consumed by the
[`roadside-lidar-background-subtraction`](https://github.com/HighwayScene/roadside-lidar-background-subtraction)
repository. They are separate from the optional `object_list` field in the
Protobuf schema.

## Record format

Each `.pb` file is a sequence of messages. Every message consists of a
four-byte unsigned little-endian payload length followed by one serialized
`highwayscene.frame.Frame` message:

```text
[uint32 payload bytes][serialized Frame][uint32 payload bytes][serialized Frame]...
```

The schema is available under [`proto/highwayscene`](proto/highwayscene). Cartesian coordinates
are interleaved little-endian `float32` values. Populated auxiliary channels
contain one value per Cartesian point:

| Field | NumPy dtype | Availability |
| --- | --- | --- |
| `cartesian` | `<f4`, shaped `(N, 3)` | all sensors |
| `intensity` | `<u2` | sensor-dependent |
| `ambient` | `<u2` | sensor-dependent |
| `velocity` | `<f4` | Aeva Aeries II |
| `reflectivity` | `<u2` | sensor-dependent |
| `timestamp_offset` | `<u8` | sensor-dependent |
| `channel_id` | `<u2` | sensors with fixed beam IDs |
| `horizontal_id` | `<u2` | Blickfeld Qb2 scan positions |

`decode_pointcloud()` validates byte alignment and channel lengths. Its default
arrays are zero-copy, read-only views. Pass `copy=True` when writable arrays
are required.

## Sensor identifiers

The HighwayScene classification sensors use these enum values:

| Sensor | `LaserName` |
| --- | --- |
| Blickfeld Qb2 | `CLASS_QB2` |
| Ouster OS0 | `CLASS_OS0` |
| Aeva Aeries II | `CLASS_AERIES_II` |

The remaining enum values are retained for wire compatibility with the
HighwayScene record format.

## Schema generation

Generated `betterproto` bindings are committed so users do not need a Protobuf
compiler. To regenerate them after an intentional schema change:

```bash
python -m pip install -e '.[codegen]'
./scripts/generate_bindings.sh
```

Never renumber or reuse an existing Protobuf field. CI verifies that committed
bindings match the schemas.

## Licensing

This reader and its Protobuf schemas are released under the [MIT License](LICENSE).
The HighwayScene dataset is distributed separately under
[CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/); using
this package does not change the dataset license.
