Configuration reference

Everything VDM knows about a venue lives in one flat text file. This page covers the file format, where the application looks for it, and what each group of keys does — starting with the ones that must be re-established on every new machine.

• Settings that must be re-established on a new laptop
• What carries over, and what does not
• File format and prefix conventions
• Where VDM looks for settings.txt
• How the file is written back
• Key reference by theme
• Stale and ignored keys

What carries over, and what does not

Beyond the four above, a second class of settings is tied to the physical camera rig rather than to the computer. These carry over perfectly — but only if the cameras have not moved.

File format and prefix conventions

settings.txt is flat key=value text, one setting per line, parsed by src/common/settings.c. There is no registry use, no %APPDATA% storage, and no secondary config file — apart from pixel_frames.txt, which is generated alongside it.

The type of a key is encoded in the key name itself, and the marker is part of the literal key — you must type it:

Comments and parsing rules

• Leading whitespace on a line is stripped.
• # at the start of a line begins a comment.
• Inside a value, a # only starts a comment when it is preceded by whitespace or sits at the very start of the value. This is deliberate: Media Foundation device paths contain # characters, and this rule lets *camera_device_path[N] survive a save/load round trip intact.
• Unrecognised keys are silently ignored. A typo in a key name is not an error — the line is skipped and the compiled-in default stands. This is the single easiest way to convince yourself you have changed a setting when you have not.
• Indexed keys use square brackets: min_motion_count[0]. Grid-line anchors are doubly indexed and the inner index is space-padded to two characters: @far[0][ 0], @far[0][10]. The padding is part of the key.

The shipped settings.txt contains no comment lines at all — it is machine-written. settings_sample.txt is the commented template, and its comments are the best short description of each key it covers.

How many keys are there

Where VDM looks for settings.txt

Configuration discovery is filesystem-based. In order:

1. The controller walks up to five parent directories from the executable's own location, looking for settings.txt.
2. Failing that, the path given as the command-line argument: VDM.exe settings_file.
3. Failing that, settings.txt in the current working directory.

In a standard C:\VDM\ installation everything is flat, so the first rule finds the file immediately. The parent-directory walk exists so that a developer running out of build\Release\ picks up the repository-root configuration without arguments.

How the file is written back

VDM does not edit settings.txt in place. When settings are saved — from the Settings tab, from Save Regions, from grid-line calibration, or at the end of auto-setup — the application rewrites the entire file from its in-memory state, writing to a temporary file and then renaming it over the original. The rename is atomic, so an interrupted save cannot leave a half-written configuration.

pixel_frames.txt is regenerated at the same time.

Take your own copy of a known-good settings.txt before any calibration session, and keep it somewhere VDM will never write.

Key reference by theme

Values shown are from the shipped live configuration. Where the commented template gives a different default, both are shown. Indexed keys are written [0..2] for per-feed values; some motion keys carry a fourth index [3] used as a global entry.

Window and display geometry

Cameras and device selection

Motion detection

Detection regions

Difference thresholds

Blob detection

Motion markers

Movie and clip logic

Encoding

Feed alignment and synchronisation

Grid lines and hill calibration

Line colours are given in YUV. meter_line_Y/U/V is 255/265/245, meter1_line_Y/U/V (whole-metre lines) is 245/265/245, and meterD_line_Y/U/V (sub-metre lines) is 245/245/265.

Anchor pairs

Each metre line is defined by two anchor points per feed:

@far[0][ 0]=960,100      far anchor for feed 0, line 0
@near[0][ 0]=960,900     near anchor for feed 0, line 0
@far[0][ 1]=985,100
@near[0][ 1]=990,900

The far anchor is where that metre mark crosses the far edge of the hill — toward the top of the frame and the vanishing point. The near anchor is the near edge, at the bottom, closer to the camera. The viewer draws the line between them and linearly interpolates distance between adjacent lines.

The key space is @far[F][I] and @near[F][I] with F = 0–2 and I = 0–29, giving 180 entries in total. Single-digit inner indices are space-padded to two characters: @far[0][ 0] through @far[0][29]. In the shipped configuration, feed 0 has anchors 0–5 populated, feeds 1 and 2 have 0–6, and the rest are 0,0.

Anchors are normally set through the Setup Grid Lines panel rather than by hand — see User guide § grid-line calibration. Each anchor is written to settings.txt immediately as you place it.

Auto-setup and analytics

Paths and upload

These appear in settings_sample.txt with the defaults below but are absent from the shipped live configuration, so the compiled-in defaults apply. Add them explicitly if you need different values.

Stale and ignored keys

Because unrecognised keys are silently dropped, both shipped files carry lines that do nothing. Knowing which they are saves you from tuning a value that has no effect.

In the live settings.txt

Two families are present but no longer read by anything — they were removed from the parser in a dead-write audit and are residue in the file:

• n_frames_of_30_before_scene_trigger_contain_motion[0..2]
• min_dist_30_frames_before_scene_trigger[0..2]

They will disappear the next time VDM rewrites the file.

In settings_sample.txt

About two dozen keys in the template are no longer recognised. The ones most likely to mislead, because they sound like things you would want to change:

Related pages

• User guide § calibration — setting motion regions and grid lines through the UI rather than by editing keys.
• Installation § first run — the camera and GPU selection steps.
• Troubleshooting § settings — recovering a configuration that was overwritten.