.. highlight:: us

.. index:: ColorScale_AddUser
.. index:: ColorMap

.. _colorscale_adduser:

ColorScale_AddUser
==================

.. us.tag ColorScale_AddUser New6805

:ref:`ColorScale_AddUser` creates or replaces a user color map. The color map
is saved in the user directory and is available after a restart and after an
update of UniPlot.

.. function::  bool = ColorScale_AddUser(ssName, svColor)

.. us.return

**Return Value**

*bool* is TRUE (1) if the color map has been saved and FALSE (0) if an error
occurred. The error message is written into the event viewer.

.. us.params

**Parameters**

.. uparam:: ssName

   *ssName* is the name of the color map. The name must not be longer than 31
   characters and must not be the name of a predefined color map (see
   :ref:`ColorScale_GetNames`). If a user color map with the same name exists,
   it will be replaced.

.. uparam:: svColor

   *svColor* is a string vector with at least two HTML colors in the format
   ``"#RRGGBB"``, e.g. ``["#00FF00", "#FF0000"]``, or a real matrix with three
   columns (red, green and blue in the range 0 to 255) and one row for each
   color, e.g. ``[0,255,0; 255,0,0]``.

.. us.comment

**Comment**

The user color maps are saved in the file :file:`Settings\\user_color_scales.rgb`
in the UniPlot user directory (see :ref:`GetUserDirectory`). The color maps can
be edited with :ref:`tools-user-color-maps`.

.. us.example

**Example**

::

   ColorScale_AddUser("MynewColorMap", ["#00FF00", "#FF0000"]);
   rmColor = ColorScale_GetColors("MynewColorMap", 10);

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2026.5
     - New.

.. seealso::
   :ref:`tools-user-color-maps`,
   :ref:`ColorScale_DeleteUser`,
   :ref:`ColorScale_GetUserNames`,
   :ref:`ColorScale_GetNames`,
   :ref:`ColorScale_GetColors`

:sub:`id-1102328`