Map editing¶

An opened map has four views, selected from the tabs at the bottom of its editor: Text (cell table), 2D (curve), 3D (surface) and 3D Sim. All are bound to the same data, so a change in one appears instantly in the others. The full ROM is shown separately as a waveform in the project window's 2d tab (see Interface).

Every view has comparison modes: Mod (current values), Ori (original), Δ (absolute difference) and % (percentage difference). They show you what a tune changed through colour and curves, without reading raw numbers.

Text (hex) view¶

Offset column on the left, then the bytes, then ASCII or a bar rendering.
View ▸ Data Width switches between 8/16/32-bit cells, Byte Order between big and little endian, and Sign between signed and unsigned interpretation.
Values can be typed directly into a cell; Enter confirms, Esc cancels.
Auto-detected candidate maps are drawn with a thin class-coloured frame + label (amber = Possible, violet = Recognized) and a small Possible/Recognized legend sits at the top-right. Right-clicking a frame promotes the candidate with Add map to list; Show auto maps toggles the whole candidate layer on and off.

2d waveform view (whole ROM)¶

The byte waveform of the entire ROM, with map blocks drawn as coloured rectangles on top. Use it to move through many maps quickly and to see trends. View ▸ Height Colours changes the colour band.

The 8/16/32/F bit and byte-order buttons on the top toolbar drive this view directly (it has no separate selector of its own).
A single click only places the cursor — it never changes the view.
Double-clicking a map region opens that map's editor and selects the map in the list on the left.
Selecting a range with the mouse also selects the same bytes in the Text (hex) view; make a selection in hex and the same range is highlighted in 2D.
Switching to the Text tab scrolls the hex view to the same position.
The Column guides button on the 2D symbol bar shows/hides the shared Text-view column guides (line breaks) in 2D; the choice is kept between sessions.

Column layout and line-break guides¶

The Text and 2D views share one column layout: change the column count or origin in one and it applies to the other immediately.

M widens the columns, W narrows them (WinOLS "more/less columns").
Ctrl+← / Ctrl+→ shift the origin one byte left/right, aligning the grid with the start of a map.
In the 2D view every column boundary is marked with a vertical line-break guide; every 4th boundary is a bolder major guide. Dragging a guide with the mouse changes the column count directly.
Range selections in 2D snap to the line breaks: a selection always starts and ends on a column boundary.
When columns are narrower than 3 pixels the guides are hidden for legibility.

Map editor tabs¶

Opening a map (from the map list or by double-clicking in 2D) shows four tabs at the bottom:

Tab	Content
`Text`	Cell table — the actual editing surface
`2D`	The map's curve, overlaid with the original according to the mode
`3D`	Surface graph; a difference heat map in `Δ`/`Ori` mode
`3D Sim`	Sliced/sectioned 3D simulation

On the 2D tab the original ROM is a dashed grey line and the modified ROM a bright line on the same axis; the area between them is shaded red for increases and blue for decreases. In Δ / % mode the curve shows the difference directly, around a zero line. The X axis is labelled with the real axis values (rpm, %, …) when the A2L/OLS data provides them, otherwise with column indices.

The Slices checkbox draws each row on its own band (WinOLS 5 "Slices"): in multi-row maps the shapes are compared without overlapping. The choice is persistent — it survives restarts.
The Style selector sets the 2D drawing style: Classic (default, plain curve), Columns (per-column separators) or WinOLS (fine value grid + square point markers). The choice is persistent.
A statistics row appears on the toolbar for the selected cells: Sel: N · min · max · avg (plus Δavg versus the original, when present). The adjacent heat legend shows the active palette and the current value range.
Tune (drag curve): in Mod mode, dragging vertically on the 2D curve writes the selected row's cells directly (drag-to-tune). Writes go through the safe cell-write path with scaling/validation and produce one undo step per drag. Writing is disabled in read-only views (Ori, Δ, %).
Hovering shows a crosshair + value readout; the row values for that column (and the original values, if any) are visible.
Selecting a column range with the mouse also selects the cells on the Text tab, and vice versa — the 2D and table selections are synchronised.
The selected column is highlighted on the 3D surface and in the 3D Sim view.

The 8/16/32/F and byte-order buttons on the top toolbar govern only the whole-ROM Text and 2D views; a map takes its cell type from the map properties.

Closing a project's last map editor clears that project's active-map highlight from the Text, 2D and 3D views.

3d surface view¶

Shows two-dimensional maps as a surface so you can judge gradients by colour and height. Editing happens on the Text tab.

When you switch to Δ or Ori mode, the surface colours the signed difference between the original and the modified data: increases red, decreases blue, with the colour intensity scaled by the magnitude of the difference. That answers "where and how much changed" in 3D at a glance. Mod mode returns you to the normal height heat map. The tinting works in both the 3D and 3D-sim views, which also gained soft directional lighting and specular shading.

Floating 3D Preview¶

View ▸ 3D Preview opens a free-floating 3D preview window for the selected map; it follows the current map as you browse the map list. Four render themes are available under View ▸ 3D Preview Theme: Dark, Blue Mesh, Green and White. The choice is persistent.

Comparison modes (Mod / Ori / Δ / %)¶

The map editor toolbar has four mode buttons:

Button	Shortcut	Shows
`Mod`	`M`	Modified/current values (editable)
`Ori`	`O`	Original ROM values (read-only)
`Δ`	`D`	Cell-by-cell absolute difference: Mod − Ori
`%`	`P`	Cell-by-cell percentage difference

Increases versus the original are tinted warm (red/orange) and decreases cold (blue); changed cells get a triangular delta flag in the corner.
Ori, Δ and % modes are read-only — no accidental writes; return to Mod mode to edit.
In Δ / % mode a delta summary row appears on the top toolbar: changed / total cells, percentage, min/avg/max difference.
The Physical / Raw Hex / Raw Dec selector chooses whether values are shown in physical units or as raw storage bits.

Editing tools¶

Operations from the Edit menu apply to the selection or to the whole map:

Operation	Effect
Value +1 / −1	Increment or decrement selected cells
Absolute change	Write a single value
Relative change	Add a percentage or an absolute delta
Slider limits	Lock cells to a range
Round	Round values to a step
Restore original	Return selected cells to their original values
Interpolation	Generate a linear or exponential ramp between two points
Smooth	Smooth neighbouring values
Flatten	Flatten the values
Repeat last operation	Apply the same edit again

Every edit can be undone: Ctrl+Z / Ctrl+Y.

Common operations also have shortcuts: + / - value +1/−1, = absolute value, % relative change, F4 repeat the last operation (Again) and F11 restore the original value. Edit ▸ Insert New Hexdump opens an extra hex window.

Edit ▸ Edit history… lists every transaction (with its description and byte range). Double-clicking a step rolls the ROM straight to that point — the hex, 2D and 3D views refresh instantly.

Quick keyboard editing¶

With cells selected in the map table you apply maths directly by pressing a key; a small dialog asks for the value:

Key	Action
`%` or `*`	Scale selected cells by a percentage (`105` → +5%)
`/`	Apply a division ratio
`=`	Set all selected cells to an absolute value
`+` / `-`	Increment / decrement in fine steps
`I`	Interpolate between the selection ends (fill in intermediate values)
`S`	3×3 weighted smoothing filter
`Enter` / `F2`	Open the inline cell editor; `Enter` confirms and moves down a row
`Esc`	Cancel the edit
Arrow keys	Move between cells; `Shift` extends the selection

The Selection menu works in both the Text and 2D views:

Command	Effect
Select Cell / Column / Row / Screen / Nothing	Select a cell / column / row / screen, or clear the selection
Invert Selection	Invert the current selection
Restore Last Selection	Bring back the previous selection
Selection to Start / End	Move the selection to the start / end of the ROM
Save / Load Selection…	Save / load the selection to a `.sel` file
Selection → Map… (`K`)	Turn the selected byte range into a new map
Support map selection	Estimate the column count + origin for the selected range

Support map selection tries to fit the byte block you selected onto a WinOLS-style grid: it finds the most likely column count and origin and applies them.

Region edits¶

Select a cell range to change only part of a map. Patch and pack files describe the same with row_start, row_end, col_start and col_end, so only that region is written instead of the whole map.

Working with scaling¶

You see values in the physical domain (bar, °C …); the application converts them to raw bytes through the scaling rule. Change scaling in the Map Properties dialog instead of scaling by hand:

Factor and offset,
Byte order — in some A2L files the cell bytes are reversed,
the unit label.

If the scaling is wrong, every edit is written wrong — which is why importing from A2L is the preferred path.

Map properties¶

Double-click a map to open its properties: name, description, unit, start address, type (MAP / CURVE / VALUE), dimensions and scaling. The From hexdump cursor button next to the address field assigns the address you are currently on in the hex view.

Find and replace¶

The Find menu covers:

Address — a given offset,
Value — cells containing a number,
Map — search and filter by name,
Similar files — find similar ROMs,
Find bytes… (Ctrl+Shift+F) — search the active ROM for a hex byte sequence, with ?? wildcard bytes. Matches are listed in a results dialog; clicking one jumps the hex view to that address.
Replace bytes… — replace every match with a new sequence; all changes form a single undo step.
Next comment / Previous comment — step through the comments in the project.
Comments and markers — annotate and navigate.

Differences to original, printing and axis profiles¶

View ▸ Differences to Original… opens a dialog listing the changed cells; click a row to jump to that address.
View ▸ Next Difference / Previous Difference (F7 / Shift+F7) step through the differences.
Project ▸ Print… sends the tuning report to a printer or PDF.
Project ▸ Export tune report as PDF… writes the same tuning report directly to a .pdf file.
Project ▸ Export A2L (DAMOS)… exports the project's maps as an ASAP2/DAMOS .a2l description file (the counterpart to Import A2L).
View ▸ Compare two maps… opens a dialog that compares two maps side by side, cell by cell, with difference colours.
Project ▸ Save axis profile… / Load axis profile… saves and restores the active map's X/Y axis descriptors (name, unit, values).

Excel and CSV export¶

Two spreadsheet exports live in the Project menu:

Export map list as Excel… — writes the map list (name, address, size, scaling …) as a single .xls file.
Export map values… — asks for a folder and writes the cell values of every map in the project as one CSV file per map into that folder, for inspection in a spreadsheet or processing with external tools.

Sample tuning packs¶

data/tuningpacks/ holds sample .mtrpack templates derived from EDC16/EDC17 tuning guides. They carry map definitions only (addresses are 0x000000 placeholders, scales/sizes are estimates) and contain no ROM bytes.

⚠️ The addresses, sizes and scalings are unverified. Do not use any map without validating it against your own ECU/software version and A2L/DAMOS file; a wrong application can brick an ECU.

Import: Project ▸ Import Map Pack… → pick the file → tick the maps to include. Because it is definition-only, the button reads Add selected to project; only the definitions are added and no ROM byte is written.

ECU presets¶

Project ▸ Apply ECU preset… lists the JSON presets under data/ecupresets/ (the application reads them from disk, so adding a preset needs no rebuild).

Selecting a preset shows its checksum hint; the settings fields are written to empty project fields only (e.g. ecuType, ecuProducer).
If mapPack is set, the normal Import Map Pack dialog opens; you still pick which maps to apply.
Presets with verified: false appear with an (unverified) tag and raise a warning in the dialog.

⚠️ These presets are unverified skeletons: they contain no real ROM data, verified address, size or scaling. Validate every value against your own ECU/software version and A2L/DAMOS file.

Auto-map (database) — catalogue-driven map inference¶

Miscellaneous ▸ Auto-map (database)… combines a map-definition catalogue (data/ecukb/mapdefs.db, produced by tools/dataset/build_mapdefs.py) with the ROM's blind structural scanner.

Family-aware inference: the catalogue returns the maps that belong to the matching HW/SW number and ECU family. When the project family is empty it is resolved from the software number.
Offset/sector-shift alignment: when the target ROM comes from a different read method or software revision, every row's address is re-validated with a fingerprint + value signature and shifted to its real location (Relocation).
Blend with blind detection: regions the catalogue cannot cover are filled in by blind auto-detection; overlapping hits raise confidence.
Review → add to project: results appear in a sortable table with name, type, address, size, confidence and source (Database / Auto-detect / both); every row is selected up front. Deselect what you do not want and click Add selected to project. Added maps land in the Auto-inferred folder.
The ROM is unchanged: adding maps only grows the project's map list; no ROM byte is written and no undo step is created.

When the catalogue is absent (mapdefs.db not found) the tool shows blind auto-detection results only. Generate the catalogue data locally with tools/dataset/build_mapdefs.py as described in DATASET_SETUP.md.

Maintenance mode (data-driven maintenance operations)¶

Project ▸ Maintenance mode… lists maintenance operations such as DPF / EGR / AdBlue / Lambda / TVA / Flaps from the catalogue under data/tuningops/*.json. The catalogue is read from disk, so adding a JSON file needs no rebuild. The list is first filtered by the active project's ECU family; the Show all ECU families checkbox reveals the whole catalogue.

Each operation is listed with its brand, family, patch count, confidence value and — where applicable — an [UNVERIFIED] tag. The row tooltip carries the source file, software reference and read method.
Checking one or more operations activates the Preview pane: the Relocation (offset/sector-shift) report — matched, shifted, ambiguous and not found counts plus a confidence percentage — and the affected maps. Relocation first tries the patch's recorded offset; failing that it searches a bounded window around it for the byte/anchor pattern, so a patch can be carried across a software version where the address moved.
Apply writes the resolved patches of the selected operations to the ROM as a single undo step. If an unverified operation is selected the confirmation dialog calls it out.
After applying, the application checks the checksum automatically: it reports when the checksum is still valid, suggests Project ▸ Correct Checksum… when it is invalid, and raises a could not be verified warning when there is no family definition (see Verification).

⚠️ The operation catalogue may be unverified (verified: false). Do not apply any operation without validating it against your own ECU/software version and A2L/DAMOS file.

Change Recorder panel¶

View ▸ Change Recorder (hidden by default) opens a panel that records ROM edits live:

Start recording / Stop recording toggles capture; the status line shows how many changes were captured.
The list shows each edit with its offset, length and before → after bytes; the full byte string is in the row tooltip.
Copy puts the recording on the clipboard as a Lua script; Create script… writes the same content to a file as Lua or .mtrpatch text (the same as Create script from changes… in the Project menu).
Clear empties the recording.

A safe editing routine¶

Take a Project ▸ Version Snapshot before you start.
Begin with a small region and verify the result with measurements.
When you are done, package it as a .mtrpatch — the question "which ROM did I apply this to?" answers itself later.