Brain Atlas File Naming Convention

The 3D Brain Atlas tool finds atlases by scanning the atlas folder and matching filenames against a fixed naming pattern — it does not read file contents to figure out what an atlas is. If a file doesn't match the pattern exactly, the tool treats it as if it doesn't exist.

This mostly matters if you're manually copying atlas files into the atlas folder rather than creating them through Add a Custom Brain Atlas. The wizard always generates correctly-named files automatically; this page is for when you're placing files there yourself.

The four file types

Every atlas is made up of up to four files, all sharing the same <Prefix><Animal> stem:

<Prefix> — any combination of letters, digits, underscore (_), period (.), and hyphen (-). Can be blank.

<Animal> — must exactly match one of the species names the tool recognizes (matching is not case-sensitive, but the word itself must be right — no extra spaces, abbreviations, or plurals).

<Modality> — the modality abbreviation as shown in the tool's Modality dropdown (e.g. CT, MR).

<KeyType> — a label for the region set in that key file, e.g. AllRegions, AllRegionsLeft, AllRegionsRight, AllRegionsLeftRight, or a custom key name. An atlas can have more than one key file.

The one detail people get backwards

This is the most common manual-naming mistake:

.rmha and key .csv files must contain the word "Atlas". Anatomical .mhd/.raw files must not contain it.

Naming an anatomical file with "Atlas" in it (or a region map/key file without it) doesn't cause an error — it just makes that file invisible to the tool. The atlas may still appear in the list, but fail (or silently be missing its reference image or regions) when you try to use it.

No version tags or other extra text

The naming pattern is exact — nothing extra is allowed between the animal name and the rest of the filename. In particular:

• No version numbers or suffixes. A file like LabRatAtlas54.rmha will not be recognized, even though it clearly follows the general idea of the convention. Rename or duplicate it to LabRatAtlas.rmha instead of relying on the tool to understand the extra text.
• "Atlas" itself is not optional. Older files that omit it entirely (e.g. a bare LabRat.rmha) also won't be recognized.

If you have older or third-party atlas files that don't fit this pattern, don't try to make them work by editing internals or hoping the tool is lenient — just copy the .rmha and key .csv files under a correctly-named copy. Leave anatomical .mhd/.raw files alone if they already match the pattern (they usually do, since they never had the extra text to begin with).

The tool checks for you

Every time the Brain Atlas tool opens, it scans the atlas folder and reports any problems it finds, before you ever get to pick an atlas from the list:

• Duplicate names — two files that resolve to the same atlas name (the tool uses the first one, alphabetically, and ignores the rest).
• Incomplete atlases — a region map exists but its anatomical reference image and/or key file(s) are missing.
• Unrecognized files — anything with a .rmha, .mhd, or .csv extension sitting in the atlas folder that doesn't match any of the patterns above.

These show up both in the tool's log and, if anything was found, as a one-time popup summary. If you've just added files manually and see this warning, it's telling you exactly which file(s) don't fit the convention — that's the first place to look.

Quick checklist before adding files manually

• Region map ends in Atlas.rmha
• Anatomical files do not contain "Atlas" anywhere
• Key files end in Atlas-Key-<KeyType>.csv
• Animal name matches the tool's supported species list exactly
• No version numbers, dates, or other extra text anywhere in the name
• All files for one atlas share the exact same <Prefix><Animal> stem

When in doubt, use Add a Custom Brain Atlas to build the atlas instead of placing files by hand — it produces filenames that are guaranteed to match.