add docs for new colorbar things

Author: nmwsharp

cpp/source/common/scalar_quantity.md

@@ -4,6 +4,24 @@ Scalar quantities can also be used to visualize integer-valued labels such as ca
 
 Add the labels as a scalar quantity where the values just happen to be integers (each integer represents a particular class or label), and set `DataType::CATEGORICAL`. This will change the visualization to a different set of defaults, adjust some shading rules, and use a distinct color from the colormap for each label.
 
+### Color Bars
+
+Each scalar quantity has an associated color map, which linearly maps scalar values to a spectrum of colors for visualization.
+See [colormaps]([[url.prefix]]/features/color_maps) for a listing of the available maps, and use `quantity->setColorMap("cmap_name")` to choose the map.
+
+The colormap is always displayed with an inline colorbar in the structures panel, which also gives a histogram of the scalar values in your quantity.
+The limits (`vminmax`) of the colormap range are given by the two numeric fields below the colored display. You can click and drag horizontally on these fields to adjust the map range, or ctrl-click (cmd-click) to enter arbitrary custom values. 
+
+![image inline and onscreen colorbar]([[url.prefix]]/media/colorbar_options.jpg)
+
+!!! note "onscreen colorbar"
+
+    Optionally an additional onscreen colorbar, which is more similar to the colorbars used in other plotting libraries, can be enabled with `quantity->setOnscreenColorbarEnabled(true)`.
+
+    By default it is positioned automatically inline with the other UI elements, or it can be manually positioned with `quantity->setOnscreenColorbarLocation(glm::vec2(xpos,ypos))`.
+
+    You can even **export this color map to an `.svg` file** for creating figures, via the options menu, or with `quantity->exportColorbarToSVG("filename.svg")`.
+
 ### Scalar Quantity Options
 
 These options and behaviors are available for all types of scalar quantities on any structure.
@@ -12,6 +30,9 @@ These options and behaviors are available for all types of scalar quantities on
 --- | --- | --- | --- | ---
 enabled | is the quantity enabled? | `#!cpp bool isEnabled()` | `#!cpp setEnabled(bool newVal)` | [yes]([[url.prefix]]/basics/parameters/#persistent-values)
 color map | the [color map]([[url.prefix]]/features/color_maps) to use | `#!cpp std::string getColorMap()` | `#!cpp setColorMap(std::string newMap)` | [yes]([[url.prefix]]/basics/parameters/#persistent-values)
+onscreen colorbar | additional onscreen colorbar | `#!cpp bool getOnscreenColorbarEnabled()` | `#!cpp setOnscreenColorbarEnabled(bool newVal)` | [yes]([[url.prefix]]/basics/parameters/#persistent-values)
+onscreen colorbar location| where to put onscreen colorbar, `(-1,-1)` (default) means auto | `#!cpp glm::vec2 getOnscreenColorbarLocation()` | `#!cpp setOnscreenColorbarLocation(glm::vec2 newVal)` | [yes]([[url.prefix]]/basics/parameters/#persistent-values)
+save colorbar to `.svg` file | export colorbar to file | `#!cpp void exportColorbarToSVG(std::string filename)` | - | -  
 map range | the lower and upper limits used when mapping the data in to the color map| `#!cpp std::pair<double,double> getMapRange()` | `#!cpp setMapRange(std::pair<double,double>)` and `#!cpp resetMapRange()`| no
 isolines enabled | are isolines shaded (default=`false`) | `#!cpp bool getIsolinesEnabled()` | `#!cpp setIsolinesEnabled(bool newVal)`| [yes]([[url.prefix]]/basics/parameters/#persistent-values)
 isoline style | stripes or thin contour lines | `#!cpp IsolineStyle getIsolineStyle()` | `#!cpp setIsolineStyle(IsolineStyle newVal)`|  [yes]([[url.prefix]]/basics/parameters/#persistent-values)

py/source/common/scalar_quantity.md

@@ -4,6 +4,24 @@ Scalar quantities can also be used to visualize integer-valued labels such as ca
 
 Add the labels as a scalar quantity where the values just happen to be integers (each integer represents a particular class or label), and set `datatype='categorical'`. This will change the visualization to a different set of defaults, adjust some shading rules, and use a distinct color from the colormap for each label.
 
+### Color Bars
+
+Each scalar quantity has an associated color map, which linearly maps scalar values to a spectrum of colors for visualization.
+See [colormaps]([[url.prefix]]/features/color_maps) for a listing of the available maps, and use `add_scalar_quantity(..., cmap="cmap_name")` to choose the map.
+
+The colormap is always displayed with an inline colorbar in the structures panel, which also gives a histogram of the scalar values in your quantity.
+The limits (`vminmax`) of the colormap range are given by the two numeric fields below the colored display. You can click and drag horizontally on these fields to adjust the map range, or ctrl-click (cmd-click) to enter arbitrary custom values. 
+
+![image inline and onscreen colorbar]([[url.prefix]]/media/colorbar_options.jpg)
+
+!!! note "onscreen colorbar"
+
+    Optionally an additional onscreen colorbar, which is more similar to the colorbars used in other plotting libraries, can be enabled with `add_scalar_quantity(..., onscreen_colorbar_enabled=True)`.
+
+    By default it is positioned automatically inline with the other UI elements, or it can be manually positioned with `add_scalar_quantity(..., onscreen_colorbar_location=(400., 400.))`.
+
+    You can even **export this color map to an `.svg` file** for creating figures via the options menu.
+
 ### Scalar Quantity Options
 
 When adding a scalar quantity, the following keyword options can be set. These are available for all kinds of scalar quantities on all structures.
@@ -13,7 +31,10 @@ Keyword arguments:
   - `enabled` boolean, whether the quantity is initially enabled (note that generally only one quantitiy can be shown at a time; the most recent will be used)
   - `datatype`, one of `"standard"`, `"symmetric"`, `"magnitude"`, or `"categorical"`, affects default colormap and map range, and the categorical policies mentioned above
   - `vminmax`, a 2-tuple of floats, specifying the min and max range for colormap limits; the default is `None`, which computes the min and max of the data
-  - `cmap`, which [colormap](../../../features/color_maps) to use
+  - colormap keywords:
+      - `cmap`, which [colormap](../../../features/color_maps) to use
+      - `onscreen_colorbar_enabled` set to `True` to enable an additional traditional colormap 
+      - `onscreen_colorbar_location` set to screen coordinates like `(400., 400.)` to position the onscreen colorbar manually (default is automatic)
   - isoline keywords (darker-shaded stripes showing isocontours of the scalar field):
       - `isolines_enabled` are isolines enabled (default: `False`)
       - `isoline_style` one of `stripe`, `'contour` (default: `stripe`)