[Feature] Per-point custom colors

[brenocq]

Discussed in #141

^{Originally posted by @vincentjzy on September 6, 2025}

---

Feature description
Allow users to specify a unique color for each individual data point within a plot item. This provides much greater flexibility for data visualization, enabling color to be used as a fourth dimension to represent properties like temperature, density, or category. This is a highly requested feature in the original ImPlot library, as seen in issues epezent/implot#608, epezent/implot#332, and epezent/implot#298.

This can be achieved by introducing new function overloads, such as PlotScatterC, PlotLineC, and PlotSurfaceC, which would accept an additional array of ImU32 colors corresponding to each data point.

A potential function signature would look like this:
IMPLOT3D_TMP void PlotScatterC(const char* label_id, const T* xs, const T* ys, const T* zs, const ImU32* colors, int count, ...);

---

Tasks

• Define Public API: In implot3d.h, add new Plot*C function overloads for PlotScatter, PlotLine, PlotTriangle, PlotQuad, and PlotSurface. These overloads will accept a const ImU32* colors parameter.
• Extend Data Getters: In implot3d_items.cpp, create new Getter structs (e.g., GetterXYZC) that can retrieve per-point color in addition to coordinates. This will involve adding a color Indexer (e.g., IndexerIdx<ImU32>) to the getter.
• Modify Renderers: Update the Renderer structs in implot3d_items.cpp to handle per-vertex coloring.
  • RendererMarkersFill and RendererMarkersLine must be modified to fetch the color for each primitive from the new Getter instead of using a single uniform color.
  • RendererLineStrip, RendererLineSegments, and other line-based renderers need to be updated to set the color for each vertex of the line segment's quad, allowing for color interpolation.
  • RendererSurfaceFill should be adapted to use the provided color array instead of calculating colors from a colormap.
• Implement High-Level Plot Functions: In implot3d_items.cpp, implement the body of the new Plot*C functions. These functions will instantiate the new color-aware Getter structs and pass them to the appropriate Plot*Ex functions and renderers.
• Create Demo: Add a new section to implot3d_demo.cpp to showcase the per-point coloring feature. This demo should:
  • Create a sample dataset.
  • Generate a corresponding array of ImU32 colors (e.g., creating a gradient effect).
  • Call one or more of the new Plot*C functions.
  • Be added to a tab in the ShowAllDemos function.

[vincentjzy]

It seems to be a great plan of update, which could considerably enhance the flexibility of ImPlot3D. My team will be happy to participate in the development.

[brenocq]

That sounds great. Do let me know if you guys have any questions. Please leave a comment before starting to implement a feature because I'll also be helping with the coding, so that we avoid double work.

[vincentjzy]

Hi Breno @brenocq , Thanks for assigning the issue to us. We will spend a couple of days to figure out the architecture of ImPlot3D and make a brief plan of modification. Then we can discuss the implementation as well as the relevant questions. Mr Rui LI (SCUTRLee) and Mr Hongli WANG (qw-code), two of my PhD students, will be involved in the development.

[brenocq]

Hi @vincentjzy, awesome to see more people getting involved in this project. Welcome to ImPlot3D @SCUTRLee @qw-code!
Thanks for the update, your plan sounds great to me. I'll be more than happy to help with any questions.

Oh, @SCUTRLee and @qw-code, feel free to leave a comment here so I can also assign this issue to you guys.

[SCUTRLee]

Hi Breno @brenocq. I'm happy to receive your invitation. To fully demonstrate the enhanced flexibility of the color-setting features in the revised code, I have made corresponding adjustments to the demos. The following PDF document provides a detailed description of the modifications.
modified ImPlot3dDemo_LR-En.pdf

[qw-code]

Hi Breno @brenocq . I'm very glad to be involved in it. I have drafted a preliminary plan for modifying the custom color of a single point in ImPlot3D. The detailed content is following.

Modification plan for per-point custom color in ImPlot3D

The main purpose of this modification is to provide flexible per-point custom color setting in the plots of scatter, line and surface. In the modified version, users are allowed to input the values of points as a one-dimensional array with the same dimension of the arrays storing x, y and z coordinates. The input values are converted to color according to the selected colormap. The specific modifications consist of three parts: data preparation, primitive rendering, and modification of plot functions. The modification plan is as follows:

1. Data Preparation

If users set the color of an object through SetNextItemStyle() , the element is plot with solid color. If users choose a colormap through PushColormap() , the object is plot in a per-point custom color style. The color array is first converted from the input values through ConvertValueToColor() . Then the value of color can be obtained through the GetterXYZ() . The relevant modifications include adjustment of GetterXYZ class, addition of ConvertValueToColor(), and minor revision of IndexerIdx to be compatible with ImU32 color.

(1) Modify the GetterXYZ class

Add a member variable to store the color (with the variable type of IndexerIdx<ImU32>) in the GetterXYZ class. Modify the constructor to support input of color data and add a member function for obtaining the color data:

- The new constructor for receiving color data
- The variable IndexerColor used for storing color data
- The member function GetColor(int idx) for obtaining the color 

The detailed modification of the GetterXYZ class is as follows:

template <typename _IndexerX, typename _IndexerY, typename _IndexerZ> struct GetterXYZ {
    // Current constructor
    // GetterXYZ(_IndexerX x, _IndexerY y, _IndexerZ z, int count) : IndexerX(x), IndexerY(y), IndexerZ(z), Count(count) {}

    // Modify the constructor to support the input of cs parameters (color array)
    GetterXYZ(_IndexerX x, _IndexerY y, _IndexerZ z, IndexerIdx<ImU32> color, int count) : IndexerX(x), IndexerY(y), IndexerZ(z), IndexerColor(color), Count(count) {}
    
    // Add a function to acquire the value of color.
    template <typename I> IMPLOT3D_INLINE ImU32 GetColor(I idx){
        return IndexerColor(idx);
    }
    const _IndexerX IndexerX;
    const _IndexerY IndexerY;
    const _IndexerZ IndexerZ;
    const IndexerIdx<ImU32> IndexerColor; // Add the variable "IndexerColor" for storing color data 
    const int Count;
};

(2) New Function: ConvertValueToColor()

The function ConvertValueToColor() is designed to convert the values of points (array cs in input) into color (array color in input).

template<typename T> bool ConvertValueToColor(const T* cs, ImU32* color, int count, double scale_max, double scale_min){
    // check input is valid
    if(count<1) return false;
    if((scale_min != 0.0 || scale_max != 0.0)&&scale_min>=scale_max) return false;

    ImPlot3DContext& gp = *GImPlot3D;
    ImPlot3DStyle& style = gp.Style;
    ImPlot3DNextItemData& n = gp.NextItemData;
    
    // Determine whether it is a fixed color or to use the colormap based on IsColorAuto
    // If it is a fixed color, then use the colors in n.Colors (the fixed color is set using the SetNextItemStyle function) 
    // If using a Colormap, it is necessary to calculate the color data corresponding to the cs data (the colormap is set through the PushColormap function)
    if(IsColorAuto(n.Colors[ImPlot3DCol_Line])||IsColorAuto(n.Colors[ImPlot3DCol_Fill])||IsColorAuto(n.Colors[ImPlot3DCol_Outline])||IsColorAuto(n.Colors[ImPlot3DCol_MarkerFill])){
        // Calculate the color mapping range
        float min = FLT_MAX;
        float max = -FLT_MAX;
        for (int i = 0; i < count; i++) {
            min = ImMin(min, cs[i]);
            max = ImMax(max, cs[i]);
        }
        // If the user specifies a mapping range, then use the specified range
        if (scale_min != 0.0 || scale_max != 0.0) {
            min = (float)ScaleMin;
            max = (float)ScaleMax;
        }
        // convert the data in cs to ImU32 color
        for(int idx=0; idx<count; idx++){
            ImVec4 col = SampleColormap(ImClamp(ImRemap01(cs[idx], min, max), 0.0f, 1.0f),style.Colormaps[0]);
            color[idx] = ImGui::ColorConvertFloat4ToU32(col);
        }          
    }
    return true;      
}

(3) Modify the IndexerIdx class

The IndexerIdx class is used to encapsulate the original data array and provide flexible access (parameters including offset and stride can be specified to handle non-contiguous memory access). The original code only provides access to double-precision data. Modify this class to provide access to ImU32 type color data functionality.

template <typename T> struct IndexerIdx {
    IndexerIdx(const T* data, int count, int offset = 0, int stride = sizeof(T)) : Data(data), Count(count), Offset(offset), Stride(stride) {}
    // The current code only provides the return value of double-precision.
    // template <typename I> IMPLOT3D_INLINE double operator()(I idx) const { return (double)IndexData(Data, idx, Count, Offset, Stride); }
    
    // The modified code is compatible with the ImU32 color data return type.
    template <typename I> IMPLOT3D_INLINE T operator()(I idx) const { return IndexData(Data, idx, Count, Offset, Stride); }

    const T* Data;
    int Count;
    int Offset;
    int Stride;
};

2. Primitive Rendering

(1) Modifying the RendererXXX Class

The classes related with primitive rendering include RendererMarkersFill, RendererMarkersLine, RendererLineStrip, and RendererSurfaceFill. The original code in the constructor of the RendererXXX class received the specified color, and then calculated the color data at each point in the Init and Render functions. In the modified version, the color is obtained directly through GetterXYZ. As an example, the specific modification for RendererSurfaceFill is as follows:

• Constructor function

template <class _Getter> struct RendererSurfaceFill : RendererBase {
    // Current constructor
    // RendererSurfaceFill(const _Getter& getter, int x_count, int y_count, ImU32 col, double scale_min, double scale_max)
    //     : RendererBase((x_count - 1) * (y_count - 1), 6, 4), Getter(getter), XCount(x_count), YCount(y_count), Col(col), ScaleMin(scale_min),
    //       ScaleMax(scale_max) {}
    
    // The modified version (Remove ImU32 col, scale_min and scale_max from the inputs)
    RendererSurfaceFill(const _Getter& getter, int x_count, int y_count)
        : RendererBase((x_count - 1) * (y_count - 1), 6, 4), Getter(getter), XCount(x_count), YCount(y_count){}
}

• Init()

void Init(ImDrawList3D& draw_list_3d) const {
    // The codes mapping the values to colors could be removed 
    // if (n.IsAutoFill) {       
    //     float z = Getter(i).z;
    //     Min = ImMin(Min, z);
    //     Max = ImMax(Max, z);
    //     for (int i = 0; i < Getter.Count; i++) {
    //         float z = Getter(i).z;
    //         Min = ImMin(Min, z);
    //         Max = ImMax(Max, z);
    //     }
    // }
}

• Render()

IMPLOT3D_INLINE bool Render(ImDrawList3D& draw_list_3d, const ImPlot3DBox& cull_box, int prim) const {
    ImPlot3DPoint p_plot[4];
    p_plot[0] = Getter(x + y * XCount);
    p_plot[1] = Getter(x + 1 + y * XCount);
    p_plot[2] = Getter(x + 1 + (y + 1) * XCount);
    p_plot[3] = Getter(x + (y + 1) * XCount);

    // Current codes to calculate the color during render 
    // const ImPlot3DNextItemData& n = GetItemData();
    // if (n.IsAutoFill) {
    //     float alpha = GImPlot3D->NextItemData.FillAlpha;
    //     float min = Min;
    //     float max = Max;
    //     if (ScaleMin != 0.0 || ScaleMax != 0.0) {
    //         min = (float)ScaleMin;
    //         max = (float)ScaleMax;
    //     }  
    //     for (int i = 0; i < 4; i++) {
    //         ImVec4 col = SampleColormap(ImClamp(ImRemap01(p_plot[i].z, min, max), 0.0f, 1.0f));
    //         col.w *= alpha;
    //         cols[i] = ImGui::ColorConvertFloat4ToU32(col);
    //     }   
    // }
    
    // Modified version, for the modified code, if a fixed color is used, the color n.Colors[ImPlot3DCol_Fill] should be applied. If a colormap is used, the color data should be read from the getter using the GetColor(idx) function.
    ImPlot3DContext& gp = *GImPlot3D;
    ImPlot3DStyle& style = gp.Style;
    ImPlot3DNextItemData& n = gp.NextItemData;
    ImU32 cols[4];

    for(int i=0;i<4;i++){
        if(!n.IsAutoFill) cols[i] = n.Colors[ImPlot3DCol_Fill];
        else cols[i] = Getter.GetColor(i);
    }
    
}

3. Drawing Functions

(1) Overload the PlotLine(), PlotScatter(), PlotSurface, etc. Add a pointer to an array of color values, i.e. cs, into the inputs. Take PlotSurface() and PlotSurfaceEX() as examples.

• PlotSurface

// Add a point color into input, which refers to the color data; Remove the scale_min and scale_max parameter inputs, which are the range of the color conversion. The color conversion is conduced before invoke the plot function.

IMPLOT3D_TMP void PlotSurface(const char* label_id, const T* xs, const T* ys, const T* zs,const ImU32* color, int x_count, int y_count, ImPlot3DSurfaceFlags flags, int offset, int stride){
	int count = x_count * y_count;
    if (count < 4)
        return;
    GetterXYZ<IndexerIdx<T>, IndexerIdx<T>, IndexerIdx<T>> getter(IndexerIdx<T>(xs, count, offset, stride), IndexerIdx<T>(ys, count, offset, stride), IndexerIdx<T>(zs, count, offset, stride),IndexerIdx<ImU32>(color, count, offset, stride), count);
    return PlotSurfaceEx(label_id, getter, x_count, y_count, flags);
}

• PlotSurfaceEX

template <typename _Getter> void PlotSurfaceEx(const char* label_id, const _Getter& getter, int x_count, int y_count, ImPlot3DSurfaceFlags flags) {
    if (BeginItemEx(label_id, getter, flags, ImPlot3DCol_Fill)) {
        const ImPlot3DNextItemData& n = GetItemData();

        // Render fill
        if (getter.Count >= 4 && n.RenderFill && !ImHasFlag(flags, ImPlot3DSurfaceFlags_NoFill)) {
            // For the current code, if the color is fixed, it is necessary to pass the color to the renderer. If it is Colormap, then the color data needs to be calculated based on the scale_min and scale_max parameters passed in the renderer.
            // const ImU32 col_fill = ImGui::GetColorU32(n.Colors[ImPlot3DCol_Fill]);
            // RenderPrimitives<RendererSurfaceFill>(getter, x_count, y_count, col_fill, scale_min, scale_max);

            // The modified code stores the color data within the getter object, and uniformly handles fixed colors and colormaps. Therefore, there is no need to pass col_fill, scale_min, and scale_max. to the renderer.
            RenderPrimitives<RendererSurfaceFill>(getter, x_count, y_count);
        }

        EndItem();
    }
}

[vincentjzy]

Hi Breno @brenocq , my boys made the plans for code modification and demo design. Please have a look and let us know if there is any quesion. In addtion, I'm not sure if the implementation can draw a line with progressively varying color between two points. Has this function been done in ImPlot3D, ImPlot or ImGui?