foxglove-flatbuffers 0.3.7

# Foxglove FlatBuffers

[![Crates.io](https://img.shields.io/crates/v/foxglove-flatbuffers)](https://crates.io/crates/foxglove-flatbuffers)
[![Documentation](https://docs.rs/foxglove-flatbuffers/badge.svg)](https://docs.rs/foxglove-flatbuffers)

Rust bindings for Foxglove FlatBuffer message schemas.

This crate provides type-safe Rust bindings for all Foxglove FlatBuffer message types, generated from the official [Foxglove schemas](https://github.com/foxglove/foxglove-sdk/tree/main/schemas/flatbuffer).

## Features

- [x] Type-safe Rust bindings for all Foxglove FlatBuffer message types
- [x] Zero-copy deserialization using FlatBuffers
- [x] Support for reading and writing Foxglove-compatible messages
- [x] Auto-generated from official Foxglove schemas
- [x] No runtime dependencies beyond `flatbuffers`

## `no_std` Support

**This crate supports `no_std` environments with `alloc`** when using pre-generated code!

The `pre-generated` feature is enabled by default. For `no_std` support, enable the `no_std` feature:

```toml
[dependencies]
foxglove-flatbuffers = { version = "0.1", features = ["no_std"] }
```

**Limitations:**
- ✅ Reading FlatBuffer messages works in `no_std` + `alloc` environments
- ⚠️ Requires `alloc` (heap allocation) - pure `no_std` without `alloc` is not supported
- ⚠️ Writing FlatBuffer messages (using `FlatBufferBuilder`) may have limitations in `no_std` environments
- ⚠️ Some `flatbuffers` builder APIs may require `std` features

**Pre-generated Code:**

The code is already pre-generated and included in the repository. This means:
- ✅ No `flatc` compiler needed for normal usage
- ✅ Faster builds (no code generation step)
- ✅ Works in `no_std` environments with `alloc`

If you're a maintainer and need to regenerate the code (e.g., after schema updates):

```bash
./scripts/download_schemas.sh  # Download latest schemas
./scripts/generate_and_commit.sh  # Regenerate and commit code
```

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
foxglove-flatbuffers = "0.1"
flatbuffers = "24.3"
```

**Note:** By default, this crate uses pre-generated code, so you don't need the FlatBuffers compiler (`flatc`) installed. The code is already included in the repository.

## Prerequisites

**No prerequisites required by default!** The crate uses pre-generated code that's included in the repository.

If you want to generate code at build time instead (by disabling the default `pre-generated` feature), you'll need the FlatBuffers compiler (`flatc`):

### macOS

```bash
brew install flatbuffers
```

### Linux (Ubuntu/Debian)

```bash
sudo apt-get install flatbuffers-compiler
```

### Other Platforms

Download from: https://github.com/google/flatbuffers/releases

## Usage

### Reading FlatBuffer Messages

```rust
use foxglove_flatbuffers::*;
use flatbuffers::GetRoot;

// Your FlatBuffer bytes
let data: &[u8] = /* ... */;

// Read a Time message (example)
// Note: Actual API depends on generated code structure
// let time = Time::get_root_as_root(data);
```

### Writing FlatBuffer Messages

```rust
use foxglove_flatbuffers::*;
use flatbuffers::{FlatBufferBuilder, WIPOffset};

// Create a builder
let mut builder = FlatBufferBuilder::new();

// Build your message using the generated types
// (Example - actual API depends on generated code)
// let time_offset = Time::create(&mut builder, &time_args);

// Finish the buffer
// builder.finish(time_offset, None);
// let finished_data = builder.finished_data();
```

## Development

### Setting Up

1. Clone the repository
2. Build the crate (no `flatc` needed - uses pre-generated code):
   ```bash
   cargo build
   ```

**For maintainers:** If you need to regenerate the code:
1. Install `flatc` (see Prerequisites above)
2. Download schemas:
   ```bash
   ./scripts/download_schemas.sh
   ```
3. Regenerate code:
   ```bash
   ./scripts/generate_and_commit.sh
   ```

### Project Structure

```
foxglove-flatbuffers/
├── Cargo.toml          # Crate configuration
├── build.rs            # Build script for code generation (when pre-generated disabled)
├── schemas/            # FlatBuffer schema files (.fbs) - optional, for regeneration
├── scripts/
│   ├── download_schemas.sh      # Script to download schemas
│   └── generate_and_commit.sh   # Script to regenerate code
└── src/
    ├── lib.rs          # Library entry point
    └── generated/      # Pre-generated Rust code (included in repo)
        └── foxglove/   # Generated message types
```

## Supported Message Types

This crate supports all Foxglove FlatBuffer message types, including:

- `Time`, `Duration`
- `Pose`, `PoseInFrame`, `PosesInFrame`
- `Point2`, `Point3`, `Vector2`, `Vector3`
- `Quaternion`
- `SceneUpdate`, `SceneEntity`
- `PointCloud`, `LaserScan`
- `CompressedImage`, `RawImage`
- `CameraCalibration`
- `LocationFix`, `GeoJSON`
- And many more...

See the [Foxglove schemas repository](https://github.com/foxglove/foxglove-sdk/tree/main/schemas/flatbuffer) for the complete list.

## License

This project is licensed under the MIT License.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Related Projects

- [Foxglove Studio](https://foxglove.dev/) - Robotics visualization platform
- [Foxglove Schemas](https://github.com/foxglove/foxglove-sdk/tree/main/schemas/flatbuffer) - Message schema definitions
- [FlatBuffers](https://flatbuffers.dev/) - Efficient cross-platform serialization library