[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.

---

Tasks

• Study ImPlot's implementation (Feat: Per-Index Color/Size Support with ImPlotSpec epezent/implot#672)
• Add LineColors to ImPlot3DSpec
• Add FillColors to ImPlot3DSpec
• Add MarkerLineColors to ImPlot3DSpec
• Add MarkerFillColors to ImPlot3DSpec
• Add MarkerSizes to ImPlot3DSpec
• Update PlotLine, PlotScatter, PlotTriangle, PlotQuad
• Create demo plots

[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?

[brenocq]

Hi @vincentjzy @SCUTRLee @qw-code! Thank you soooo much for the detailed description of the changes (and sorry for taking so long to reply!). As @vincentjzy already know, I'm now also maintaining ImPlot, so I was focusing on merging its fixes/features there last week. Your proposed changes look solid and very much in line with what we discussed and what I had in mind.

While discussing with @epezent on how to support per-point custom colors, he pointed me to epezent/implot#519 -- the list of colors could potentially be a ImPlotProp_LineColorList (ImPlot3DProp_LineColorList for us). This would avoid having a crowded argument list. This was one of the main reason I didn't reply you before (I didn't know about this ImPlotProp discussion until last week hahaha). I personally love the ImPlotProp API since it can be very simple and clean, but also allow for a lot of customization without the Push/Pop/SetNext mess. With the current API, I do see myself getting lost on the argument list daily hahah it would be great to not need to check the function definition to understand the arguments.

It is very likely that we'll add ImPlotProp to one of the next ImPlot releases and start deprecating the SetNext APIs, I believe we should follow the same direction with ImPlot3D.

Since this is a major change, it would be much appreciated if you guys leave a comment in epezent/implot#519 with your thoughts (just saying if you like it or not is also fine). Going into the ImPlotProp direction does mean our previous discussion in this PR would become obsolete, I'm sorry I didn't realized this before you guys put so much work into it... You guys do have a really good understand of the inner workings of ImPlot/ImPlot3D now, so I would very much appreciate your help maintaining ImPlot/ImPlot3D :)