Add support for custom SVG cell colors and validation in PhysiCell settings

[drbergman]

User-configurable SVG cell type colors

Motivation

paint_by_number_cell_coloring() previously had two limitations:

1. Hard cap at 13 cell types. Models with 14 or more cell types would render all extra cells as white — invisible against a white background and indistinguishable from each other.
2. No user control. Colors were fully hard-coded; users who wanted a specific cell type to appear in a specific color had no mechanism to express that in the config file.

What changed

Automatic color generation for extra cell types (always active)

The 13-color hard cap is removed. For any model with more than 13 cell types and no user-specified colors, extra types are now assigned colors automatically using golden-angle HSV spacing (137.5° hue steps, saturation 0.65, value 0.85). This guarantees perceptual separation between consecutive colors and produces the same sequence regardless of how many cell types the model has.

Optional per-cell-type color overrides via XML

A new optional <cell_colors> element can be placed inside <save><SVG> in the config XML. Each child <cell_color name="..."> maps a cell definition name to an SVG color string. Partial coverage is supported — only the cell types you want to override need entries; all others fall back to the automatic assignment.

When <cell_colors> is present, colors that the user has explicitly claimed are removed from the automatic pool before it is handed to unspecified cell types. For example, if my_special_cell_type is assigned green, then the remaining cell types cycle through grey, red, yellow, (green skipped), blue, etc.

Validation

Two error conditions halt the simulation with a clear message:

• A <cell_color name="..."> whose name does not match any cell definition in the model.
• A color value that is not a recognized SVG color (not a CSS named color, #rrggbb/#rgb hex, or rgb(r,g,b) functional notation). This catches typos like "corral" before they silently render as black.

Files changed

File	Change
modules/PhysiCell_settings.h	Added svg_cell_colors_specified flag and svg_cell_colors_by_name map to PhysiCell_Settings
modules/PhysiCell_settings.cpp	Parses the optional <cell_colors> block from <save><SVG>
modules/PhysiCell_pathology.cpp	Rewrote color-table setup in paint_by_number_cell_coloring(); added hsv_to_svg_color() and is_valid_svg_color() helpers
modules/PhysiCell_pathology.h	Added <algorithm>, <unordered_set> includes
config/PhysiCell_settings.xml	Added commented usage example inside <SVG>

Usage

Add a <cell_colors> block inside <save><SVG> in your config XML. You can specify any subset of your cell types — or none at all.

<SVG>
    <interval units="min">60</interval>
    <enable>true</enable>
    <cell_colors>
        <cell_color name="cancer cell">red</cell_color>
        <cell_color name="immune cell">cyan</cell_color>
        <cell_color name="stroma">rgb(210,180,140)</cell_color>
        <cell_color name="vessel">#8B0000</cell_color>
    </cell_colors>
</SVG>

Accepted color formats:

• CSS named colors: red, coral, lightskyblue, … (full list at MDN)
• Hex: #rgb or #rrggbb
• Functional: rgb(r,g,b) with integers 0–255

Cell types not listed receive colors drawn from the standard palette in order, with any user-claimed colors skipped. If the standard palette is exhausted, additional colors are generated automatically.

[Copilot]

Pull request overview

Adds optional user-configurable per-cell-type SVG colors via a new <cell_colors> XML block, removes the hard 13-cell-type color cap by auto-generating extra colors with golden-angle HSV spacing, and validates user-supplied names and color strings before use.

Changes:

• New svg_cell_colors_specified flag and svg_cell_colors_by_name map on PhysiCell_Settings, populated from <save><SVG><cell_colors> in XML.
• Rewrote paint_by_number_cell_coloring() to support partial user overrides, skip claimed built-in colors, and fall back to HSV-generated colors; added is_valid_svg_color() and hsv_to_svg_color() helpers.
• Added a (commented-out) usage example in config/PhysiCell_settings.xml.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
modules/PhysiCell_settings.h	Adds <map> include and new color-config fields on PhysiCell_Settings.
modules/PhysiCell_settings.cpp	Parses optional <cell_colors>/<cell_color> entries from the SVG block.
modules/PhysiCell_pathology.h	Adds <algorithm> and <unordered_set> includes for new helpers.
modules/PhysiCell_pathology.cpp	Implements color validation, HSV color generation, and revised palette assignment in paint_by_number_cell_coloring.
config/PhysiCell_settings.xml	Adds commented usage example of <cell_colors>; its description contradicts the implemented (partial-coverage) behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jeanettejohnson]

this will allow people to map colors however they want which is awesome, but does that option only kick in over 13 cell types? This looks great to me

[drbergman]

this will allow people to map colors however they want which is awesome, but does that option only kick in over 13 cell types? This looks great to me

See:

Optional per-cell-type color overrides via XML

A new optional <cell_colors> element can be placed inside in the config XML. Each child <cell_color name="..."> maps a cell definition name to an SVG color string. Partial coverage is supported — only the cell types you want to override need entries; all others fall back to the automatic assignment.

When <cell_colors> is present, colors that the user has explicitly claimed are removed from the automatic pool before it is handed to unspecified cell types. For example, if my_special_cell_type is assigned green, then the remaining cell types cycle through grey, red, yellow, (green skipped), blue, etc.