matlab-point-cloud-file-io

# Point Cloud File I/O

Read and write 3-D point cloud data in MATLAB using Lidar Toolbox file I/O functions, covering PLY, PCD, LAS/LAZ, sensor PCAP, E57, and IDC (Ibeo) formats.

## When to Use

- Loading a point cloud file from disk into a `pointCloud` object
- Saving a `pointCloud` object to disk in any supported format
- Deciding which reader or writer function to use for a given file format
- Reading LAS/LAZ files with selective filtering (ROI, classification, GPS time)
- Extracting or preserving lidar point attributes (classification, GPS timestamps, scan angle)
- Reading Velodyne, Ouster, or Hesai PCAP sensor recordings frame-by-frame
- Reading multi-scan E57 files with indexed access
- Reading Ibeo IDC sensor recordings with message-based access
- Converting between point cloud formats (e.g., LAS to PLY, PCD to LAZ)

## When NOT to Use

- Streaming live sensor data in real time (use `velodynelidar`, `ousterlidar`, `sicklidar`)
- Processing or filtering point clouds after reading (use `pcdownsample`, `pcdenoise`)
- Reading or writing surface meshes (use `readSurfaceMesh`, `writeSurfaceMesh`)
- Saving point cloud variables to MAT-files (use `save`)
- Visualizing point clouds (use `pcshow`, `pcplayer`, `pcviewer`)

## Must-Follow Rules

1. **Route by file extension, not by habit** — `pcread` ONLY supports `.ply` and `.pcd` files. For `.las`/`.laz` use `lasFileReader` + `readPointCloud`. For `.pcap` use the sensor-specific file reader (`velodyneFileReader`, `ousterFileReader`, or `hesaiFileReader`). For `.e57` use `e57FileReader`. Calling `pcread` on a LAS or PCAP file produces an error, not a warning. Similarly, `pcwrite` ONLY writes PLY and PCD — for LAS/LAZ output use `lasFileWriter` + `writePointCloud`.

2. **PCAP file readers require a mandatory device identifier — never guess it** — `velodyneFileReader` requires a `DeviceModel` string (e.g., `"HDL32E"`). `hesaiFileReader` requires a `DeviceModel` string (e.g., `"PandarXT32"`). `ousterFileReader` requires a `CalibrationFile` path (JSON). If the user has not specified the device model or calibration file, ASK — do not assume a default. There is no default value; omitting it causes an error.

3. **Use two-output syntax to get point attributes from LAS/LAZ** — `[ptCloud, ptAttributes] = readPointCloud(reader)` returns a `lidarPointAttributes` object containing Classification, GPSTimeStamp, LaserReturn, NumReturns, ScanAngle, and more. The single-output form discards these attributes permanently. Intensity is on the `pointCloud` object (`.Intensity` property), NOT on `lidarPointAttributes`.

4. **Preserve attributes with three-argument writePointCloud** — `writePointCloud(writer, ptCloud, ptAttributes)` preserves Classification, GPSTimeStamp, and other lidar attributes in LAS/LAZ output. The two-argument form `writePointCloud(writer, ptCloud)` discards all attributes. If the user has attributes from `lasFileReader`/`readPointCloud`, always pass them through.

5. **PLY only supports ascii and binary encoding** — Calling `pcwrite(ptCloud, "file.ply", Encoding="compressed")` throws an error. Only `"ascii"` and `"binary"` are valid for PLY. The `"compressed"` encoding is exclusive to PCD format. Defaults (R2026a+): PLY=`"binary"`, PCD=`"compressed"`.

6. **Always use string syntax** — Use double-quoted strings (`"text"`) for all literal text arguments (filenames, device models, encoding values, Name=Value values). Use `Name=Value` syntax for all name-value pairs. Never use character vectors (`'text'`) or legacy `'Name','Value'` pair syntax.

### Preflight Procedure

1. List MATLAB functions to call
2. Check `references/INDEX.md` for each (function-level + task-level tables)
3. Read required quick-ref files
4. State at response top: `Preflight: quick-ref/xxx.md, quick-ref/yyy.md` (or `Preflight: none required`)

## Key Functions

| Function | Purpose | Format | Key Constraint |
|---|---|---|---|
| `pcread` | Read point cloud from file | PLY, PCD | Single call, returns `pointCloud` |
| `pcwrite` | Write point cloud to file | PLY, PCD | Encoding varies by format |
| `lasFileReader` | Create LAS/LAZ reader object | LAS, LAZ | Two-step: create reader, then `readPointCloud` |
| `lasFileWriter` | Create LAS/LAZ writer object | LAS, LAZ | Two-step: create writer, then `writePointCloud` |
| `velodyneFileReader` | Create Velodyne PCAP reader | PCAP | Mandatory `DeviceModel` (2nd arg) |
| `ousterFileReader` | Create Ouster PCAP reader | PCAP | Mandatory `CalibrationFile` (2nd arg) |
| `hesaiFileReader` | Create Hesai PCAP reader | PCAP | Mandatory `DeviceModel` (2nd arg) |
| `e57FileReader` | Create E57 reader object | E57 | Use `readPointCloud(reader, idx)` for multi-scan |
| `ibeoLidarReader` | Create Ibeo IDC reader object | IDC | Use `readMessages` to read scan data |

## Decision Framework

```
READING — What is the file extension?
├── .ply / .pcd → pcread(filename)
├── .las / .laz → lasFileReader(filename) + readPointCloud(reader)
├── .pcap (Velodyne) → velodyneFileReader(filename, deviceModel)
├── .pcap (Ouster)  → ousterFileReader(filename, calibrationFile)
├── .pcap (Hesai)   → hesaiFileReader(filename, deviceModel)
├── .e57           → e57FileReader(filename) + readPointCloud(reader, idx)
└── .idc (Ibeo)    → ibeoLidarReader(filename) + readMessages(reader)

WRITING — What output format does the user need?
├── .ply → pcwrite(ptCloud, "file.ply")
│         Encoding: "ascii" or "binary" (default: binary)
├── .pcd → pcwrite(ptCloud, "file.pcd")
│         Encoding: "ascii", "binary", or "compressed" (default: compressed)
├── .las → lasFileWriter("file.las") + writePointCloud(writer, ptCloud)
└── .laz → lasFileWriter("file.laz") + writePointCloud(writer, ptCloud)
           Optional: pass ptAttributes as 3rd arg to preserve attributes
```

**PCAP sensor identification:** If the user says "Velodyne", "Ouster", or "Hesai" — use the matching reader. If they just say "PCAP file" without specifying the sensor, ASK which sensor produced it.

**Ib