openscenario-rs 0.3.2

Rust library for parsing and manipulating OpenSCENARIO files
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

# openscenario-rs

<p align="center">
<img src="docs/assets/openscenario-rs-badge-vertical.svg" alt="openscenario-rs logo" width="160"/>
</p>

A Rust library for parsing, validating, and manipulating [OpenSCENARIO](https://www.asam.net/standards/detail/openscenario/) files.

[![Crates.io](https://img.shields.io/crates/v/openscenario-rs)](https://crates.io/crates/openscenario-rs)
[![Documentation](https://docs.rs/openscenario-rs/badge.svg)](https://docs.rs/openscenario-rs)
[![License](https://img.shields.io/badge/license-GPLv3-blue.svg)](LICENSE)

## Features

- Parse and serialize `.xosc` files (scenarios, catalogs, parameter variations)
- Type-safe data model covering actions, conditions, entities, and distributions
- Parameter resolution with mathematical expression support (`${param + 1}`)
- Catalog loading and reference resolution
- Optional builder API for programmatic scenario construction (`--features builder`)
- CLI tools: `xosc-validate`, `scenario_analyzer`

## Status

Core parsing and serialization is functional. Actions and conditions have broad but not complete coverage — see the implementation table in [docs/user_guide.md](docs/user_guide.md) for details.

## Quick Start

```toml
[dependencies]
openscenario-rs = "0.3.0"
```

### Parsing

```rust
use openscenario_rs::{parse_file, OpenScenarioDocumentType};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let scenario = parse_file("scenario.xosc")?;

    println!("Author: {:?}", scenario.file_header.author);

    match scenario.document_type() {
        OpenScenarioDocumentType::Scenario => {
            if let Some(entities) = &scenario.entities {
                for entity in &entities.scenario_objects {
                    println!("Entity: {:?}", entity.name);
                }
            }
        }
        OpenScenarioDocumentType::Catalog => println!("Catalog file"),
        OpenScenarioDocumentType::ParameterVariation => println!("Parameter variation file"),
        _ => {}
    }

    Ok(())
}
```

### Analysis Tools

```bash
cargo run --bin scenario_analyzer -- scenario.xosc
cargo run --bin xosc-validate -- scenario.xosc
```

## Modules

- `types/` — OpenSCENARIO data types
- `parser/` — XML parsing and serialization
- `catalog/` — catalog loading and reference resolution
- `expression/` — expression evaluation
- `builder/` — programmatic scenario construction (feature-gated)

## Testing

```bash
cargo test
cargo test --features builder
```

## Documentation

- [User Guide](docs/user_guide.md)
- [Builder Guide](docs/builder_guide.md)
- [API Reference](docs/api_reference.md)
- [Design](docs/design.md)

## Contributing

Check existing patterns before adding new types. Add tests. Verify XML round-trip behavior.

## License & Attribution

The Rust source code is licensed under the [GNU General Public License v3.0](LICENSE).

### ASAM OpenSCENARIO Schema

`Schema/OpenSCENARIO.xsd` is published by ASAM e.V. and redistributed unchanged for validation purposes under the [ASAM license terms](https://www.asam.net/license/). See [`Schema/NOTICE`](Schema/NOTICE) for details.

### ALKS Test Scenarios

`tests/data/alks_scenario.xosc` originates from [openMSL/sl-3-1-osc-alks-scenarios](https://github.com/openMSL/sl-3-1-osc-alks-scenarios) (© BMW Group), licensed under [MPL 2.0](https://www.mozilla.org/en-US/MPL/2.0/). See [`tests/data/NOTICE`](tests/data/NOTICE) for details.

## Acknowledgement

<p align="center">
<img src="docs/assets/synergies.svg" alt="Synergies logo" width="200"/>
</p>

This package is developed as part of the [SYNERGIES](https://synergies-ccam.eu/) project.

<p align="center">
<img src="docs/assets/funded_by_eu.svg" alt="Funded by EU" width="200"/>
</p>

Funded by the European Union. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or European Climate, Infrastructure and Environment Executive Agency (CINEA). Neither the European Union nor the granting authority can be held responsible for them.