matlab-use-ncap-protocol

# Generate Euro NCAP Variants

Create Euro NCAP seed scenarios, generate variants, translate between simulators, plot descriptors, and compute scores using the ADT Euro NCAP support package APIs.

## When to Use

- Creating Euro NCAP seed scenarios (any protocol year)
- Generating scenario variants from seeds
- Translating scenarios between drivingScenario and RoadRunner via descriptors
- Plotting scenario descriptors (single or multi-descriptor grids)
- Computing NCAP scores and generating/exporting reports
- Any workflow mentioning Euro NCAP test names (CCRs, CCFtap, CCCscp, CPNA, etc.)

## When NOT to Use

- Building custom drivingScenario from scratch (roads, lanes, actors) — use drivingScenario core APIs directly
- RoadRunner scene/project management (creating projects, importing assets) — use RoadRunner scene APIs
- Custom `variationProperties` for non-NCAP scenarios
- Simulink co-simulation or AEB test bench setup

## Decision Tree: Which API Path?

```
User wants Euro NCAP scenarios?
│
├─ Protocol year 2023 (or unspecified)?
│   └─ Use standalone: ncapScenario("SA AEB CCFtap")
│      - Test names use prefix: "SA AEB", "SA LSS", "VRU AEB", "VRU LSS"
│      - Supports ShowProgress name-value
│      - Returns ScenarioDescriptor
│
└─ Protocol year 2026?
    └─ Use euroAssessment path:
       1. ea = euroAssessment(2026)
       2. configureVUT(ea, ...) — if custom VUT needed
       3. descriptor = ncapScenario(ea, "CA FC CCFtap")
       - Test names use prefix: "CA FC"
       - Does NOT support ShowProgress
       - Required for scoring/reporting workflow
```

## Key Functions

| Function | Purpose | Available From |
|----------|---------|----------------|
| `ncapScenario` | Generate seed descriptor(s) from test name | R2024a |
| `euroAssessment` | Store 2026 protocol specs and scores | R2025a |
| `configureVUT` | Set StabilizationTime, AssetPath on euroAssessment | R2026a |
| `getScenario` | Convert descriptor → drivingScenario or RoadRunner | R2022b |
| `getScenarioDescriptor` | Extract descriptor from existing drivingScenario | R2022b |
| `generateVariants` | Generate variant descriptors from seed + variationProperties | R2023a |
| `plot` (ScenarioDescriptor) | Plot descriptor(s), returns ScenarioDescriptorPlot | R2026a |
| `configure` (ScenarioDescriptorPlot) | Set GridSize, Title, SubPlotTitles, CropType | R2026a |
| `assessmentTable` | Create empty assessment table for a test | R2025a |
| `ncapScore` | Compute score from assessment table (returns struct) | R2025a |
| `ncapReport` | Generate visual report figure | R2025a |
| `exportReport` | Export report to PDF/PNG/JPG file | R2026a |
| `table2scenario` | Create ScenarioDescriptor from tabular data (sceneSpec, actorSpec, eventSpec) | R2024a |
| `exportScenario` (roadrunner) | Export from RoadRunner to OpenSCENARIO | R2022a |

## Pattern: Seed-Only Generation

Use when you need just the seed scenario (1 descriptor), not all variants.

```matlab
% 2023 standalone — single seed
descriptor = ncapScenario("SA AEB CCFtap");

% 2026 via euroAssessment — single seed
ea = euroAssessment(2026);
descriptor = ncapScenario(ea, "CA FC CCFtap");
```

`AllScenarios=true` generates the seed AND all protocol-defined variants. Do NOT use it when only the seed is requested.

**Output arguments:** The two-output form `[descriptors, scenarioInfo] = ncapScenario(...)` requires `AllScenarios=true`. Without it, only one output is allowed — requesting two outputs errors with "Too many output arguments".

## Pattern: All Variants Generation

Use when the user wants all test variants for a given scenario.

```matlab
% 2023 — all variants with progress
[descriptors, scenarioInfo] = ncapScenario("SA AEB CCCscp", AllScenarios=true);

% 2026 — all variants
ea = euroAssessment(2026);
[descriptors, scenarioInfo] = ncapScenario(ea, "CA FC CCCscp", AllScenarios=true);
```

## Pattern: ShowProgress

The `ShowProgress` name-value controls built-in progress display during generation.

```matlab
% Show command-line progress (default behavior)
descriptor = ncapScenario("SA AEB CCRs", ShowProgress="CommandLine");

% Suppress progress
descriptor = ncapScenario("SA AEB CCRs", ShowProgress="No");
```

**Important:** `ShowProgress` is only supported on the standalone `ncapScenario(testName)` call. It is NOT supported when using the `euroAssessment` overload `ncapScenario(ea, testName)`.

When the user asks to "show progress" or "display progress", use `ShowProgress="CommandLine"` (or omit it since it's the default). Do NOT set `ShowProgress="No"` and then implement manual fprintf progress.

## Pattern: DSD ↔ RoadRunner Translation

Use `getScenario` to translate a descriptor to either simulator. Never export to OpenSCENARIO and re-import as a translation method.

```matlab
% Descriptor → drivingScenario
ds = getScenario(descriptor, Simulator="DrivingScenario");

% Descriptor → RoadRunner (requires active RoadRunner instance)
rrApp = roadrunner("C:/path/to/project");
rrScen = getScenario(descriptor, Simulator="RoadRunner", SimulatorInstance=rrApp);
```

**Key rules:**
- `getScenario` requires Name-Value syntax. `Simulator` must be specified as a Name-Value pair, not a positional argument.
- With `Simulator="DrivingScenario"`: accepts an array of descriptors and returns an array of `drivingScenario` objects.
- With `Simulator="RoadRunner"`: accepts only a **single descriptor** per call — returns one `Simulink.ScenarioSimulation` object. Passing an array errors with "Too many input arguments". Loop over descriptors individually for batch RoadRunner translation.

## Pattern: ScenarioDescriptorPlot

### Configure options

| Property | Values | Notes |
|----------|--------|-------|
| `GridSize` | `[rows cols]`, max product = 20 | Error if > 20 subplots |
| `Title` | string | Figure title |
| `SubPlotTitles` | string array | Must match descriptor count exactly |
| `CropType` | `"None"`, `"GlobalWaypoint"`, `"DynamicWaypoint"`, `"RuntimeActorsCrop"` | Controls plot cropping |

###