Custom Simulation Visualization Settings ======================================== CompuCell3D can store simulation-specific visualization settings in two formats: ``_settings.sqlite`` The standard simulation settings database used by Player. ``_custom_settings.xml`` A portable XML representation of selected simulation settings. This file is convenient for version control, sharing settings with collaborators, and applying Player-generated visualization settings to Python-only simulations. The XML file is optional. When it is present, its settings are loaded on top of the normal default/global settings. In other words, values in ``_custom_settings.xml`` override the values that would otherwise come from default or global settings. Where Settings Files Are Stored ------------------------------- For a regular ``.cc3d`` project, settings are stored in the project's ``Simulation`` folder:: MySimulation/ MySimulation.cc3d Simulation/ _settings.sqlite _custom_settings.xml For Python-only simulations, place ``_custom_settings.xml`` in the same folder as the Python script that starts the simulation. For example:: CompuCell3D/core/Demos/CC3DPy/scripts/ SortingDemo.py ChemotaxisDemo.py _custom_settings.xml When a Python-only simulation starts, CC3D checks the folder containing the top-level Python script. If it finds ``_custom_settings.xml``, it loads those settings before visualization windows are created. Selecting a Global Settings Directory Name ------------------------------------------ Player normally reads global settings from ``~/.compucell3d_py3``. You can start Player with a different global settings folder name when you need an isolated settings profile, for example when testing custom visualization settings without modifying your normal Player configuration. Use ``--global-settings-dir-name`` to choose the directory name under your home directory: .. code-block:: bash compucell3d.command --global-settings-dir-name .cc3d_project_settings -i MySimulation.cc3d On Windows, use ``compucell3d.bat``: .. code-block:: bat compucell3d.bat --global-settings-dir-name .cc3d_project_settings -i MySimulation.cc3d On Linux, use ``compucell3d.sh``: .. code-block:: bash ./compucell3d.sh --global-settings-dir-name .cc3d_project_settings -i MySimulation.cc3d If CC3D is installed in a Python environment, you can also launch Player as a Python module: .. code-block:: bash python -m cc3d.player5 --global-settings-dir-name .cc3d_project_settings -i MySimulation.cc3d In this example Player uses ``~/.cc3d_project_settings`` for global settings. The option expects a directory name, not a full filesystem path. .. note:: The earlier option name ``--global-settings-dir`` has been replaced by ``--global-settings-dir-name``. .. admonition:: Info When running Python-only simulations, you may need to update window positions in ``_custom_settings.xml``. Window positions generated by Player and serialized to XML may not be directly compatible with windows created by Python-only visualization. This is especially noticeable when moving settings between different display setups, operating systems, or Player and CC3DPy visualization. Generating XML Settings from Player ----------------------------------- The easiest way to create ``_custom_settings.xml`` is to use Player: 1. Open and start a ``.cc3d`` simulation in Player. 2. Arrange graphics windows, choose fields, adjust scalar ranges, colors, and other visualization settings. 3. Open the ``Tools`` menu and choose ``Manage Simulation Settings...``. .. image:: images/manage_simulation_settings_menu.png :alt: Manage Simulation Settings menu action 4. In the dialog, enable ``XML Format``. 5. Click ``Export Settings``. .. image:: images/manage_simulation_settings_dialog.png :alt: Manage Simulation Settings dialog Player writes: - ``Simulation/_settings.sqlite`` - ``Simulation/_custom_settings.xml`` when ``XML Format`` is enabled To use these settings with a Python-only simulation, copy ``_custom_settings.xml`` into the folder containing the Python script that starts the simulation. Basic XML Structure ------------------- The settings XML file has a root element named ``PlayerSettings`` and a ``Settings`` section. Each individual setting is stored as a ``Setting`` element with a name and type: .. code-block:: xml 1 1 #000000 Simple values appear as text inside the setting element. More complex values, such as dictionaries and lists, are represented using nested ``Item`` elements. Common scalar types include: ``bool`` Stored as ``1`` for true and ``0`` for false. ``int`` and ``float`` Numeric values. ``str`` Text values. ``color`` Hex RGB colors such as ``#ff0000``. ``point`` and ``size`` Two integer values separated by a comma. These are commonly used for window position and window size. Cell Type Colors ---------------- The ``TypeColorMap`` setting controls colors assigned to cell type ids. It is a dictionary where keys are integer cell type ids and values are colors: .. code-block:: xml #000000 #0000ff #008000 #ff0000 Cell type id ``0`` is normally Medium. Other ids correspond to the cell types declared in the simulation. FieldParams ----------- ``FieldParams`` stores visualization settings for scalar and vector fields. Each entry is keyed by field name. For example, the following configures a field named ``ATTR``: .. code-block:: xml 1 0.0 1 1.0 0 6 2 1 0 0 9 1 0 0 #ffffff Important entries include: ``MinRange`` and ``MaxRange`` The scalar range used for color mapping. ``MinRangeFixed`` and ``MaxRangeFixed`` Whether the range endpoints are fixed by the user instead of being computed automatically from field values. ``LegendEnable`` Controls whether the color legend is displayed. ``NumberOfLegendBoxes`` and ``NumberAccuracy`` Control legend appearance. ``ContoursOn`` and ``NumberOfContourLines`` Control contour display for scalar fields. ``OverlayVectorsOn``, ``ArrowLength``, ``ScaleArrowsOn``, ``FixedArrowColorOn``, and ``ArrowColor`` Control vector overlay rendering when vector data are displayed. If a field does not have an entry in ``FieldParams``, CC3D uses default field visualization settings for that field. WindowsLayout ------------- ``WindowsLayout`` stores graphics-window layout information. It is a dictionary of windows. Each window entry contains the scene name, window size and position, and VTK camera settings: .. code-block:: xml Cell_Field 853,-744 420,280 374.6708309603021 432.84803158060953 50.0 50.0 0.0 50.0 50.0 399.9995587361593 0.0 1.0 0.0 The most important key is ``sceneName``. CC3D uses it to match a saved layout entry to a visualization. For example, if a Python-only simulation creates windows for ``Cell_Field``, ``F1``, and ``F2``, but ``WindowsLayout`` only contains entries for ``Cell_Field`` and ``F2``, then only those two windows get their saved layout. The ``F1`` window uses the normal default visualization settings. In Python-only simulations, CC3D currently restores the window position, window size, and VTK camera settings from ``WindowsLayout``. Projection-related entries such as ``planeName``, ``planePosition``, and ``is3D`` may appear in the XML file, but Python-only visualization may ignore them. Editing XML by Hand ------------------- You can edit ``_custom_settings.xml`` in a text editor. This is useful for small changes such as adjusting colors or scalar ranges. Keep the following in mind: - Preserve the ``Name``, ``Type``, ``Key``, and ``KeyType`` attributes. - Boolean values are ``1`` and ``0``. - Colors use ``#rrggbb`` format. - Dictionary entries use nested ``Item`` elements. - XML overrides default/global settings only for settings present in the file. For larger changes, it is usually easier to arrange windows and visualization settings in Player and export a new XML file using ``Manage Simulation Settings...``. _custom_settings.xml example ---------------------------- .. code-block:: xml #ffffff 1 0 #ffffff #ffffff #ffff00 #ffffff 1 #ffffff 1 1 2 1.0 0 2 0 0 1 #0000ff 0 1 #ffffff 0 1 1 #ffffff 0 0 1 0.0 1 1.0 0 6 2 1 0 0 9 1 0 0 #ffffff 0 7 1 0 1 1.0 0 0.0 1 2 9 6 10 0 0 #000000 1 0 5 /Users/m/CC3DWorkspace/bacterium_macrophage_2D_steering_cc3d_04_15_2026_10_42_07_dfa401 1 1 100 100 100 0 10 600 600 1 1 1 1 1 #000000 salmon yellow olive #ffff00 #a52a2a #add8e6 #90ee90 #800080 #ffa500 #40e0d0 0 #000000 0 Cell_Field xy 0 0 50,50 420,280 Graphics 255.90521887869795 295.64102969784125 50.0 50.0 0.0 50.0 50.0 273.2050807568875 0.0 1.0 0.0 F2 xy 0 0 500,500 772,566 Graphics 255.90521887869818 295.6410296978415 50.0 50.0 0.0 50.0 50.0 273.20508075688775 0.0 1.0 0.0 1 1.0