- Undocumented Matlab - http://undocumentedmatlab.com -

Plot line transparency and color gradient

Posted By Yair Altman On November 13, 2014 | 43 Comments

In the past few weeks, I discussed the new HG2 axes Backdrop [1] and Baseline [2] properties with their associated ability to specify the transparency level using a fourth (undocumented) element in their Color.
In other words, color in HG2 can still be specified as an RGB triplet (e.g., [1,0,0] to symbolize bright red), but also via a 4-element quadruplet RGBA, where the 4th element (Alpha) signifies the opacity level (0.0=fully transparent, 0.5=semi-transparent, 1.0=opaque). So, for example, [1, 0, 0, 0.3] means a 70%-transparent red.
This Alpha element is not documented anywhere as being acceptable, but appears to be supported almost universally in HG2 wherever a color element can be specified. In some rare cases (e.g., for patch objects) Matlab has separate Alpha properties that are fully documented, but in any case nowhere have I seen documented that we can directly set the alpha value in the color property, especially for objects (such as plot lines) that do not officially support transparency. If anyone finds a documented reference anywhere, please let me know – perhaps I simply missed it.
Here is a simple visualization:

h1a = plot(1:5,     11:15, '.-', 'LineWidth',10, 'DisplayName',' 0.5');
h1b = plot(1.5:5.5, 11:15, '.-', 'LineWidth',10, 'DisplayName',' 1.0', 'Color',h1a.Color);  % 100% opaque
h1a.Color(4) = 0.5;  % 50% transparent
h2a = plot(3:7,  15:-1:11, '.-r', 'LineWidth',8, 'DisplayName',' 0.3'); h2a.Color(4)=0.3;  % 70% transparent
h2b = plot(2:6,  15:-1:11, '.-r', 'LineWidth',8, 'DisplayName',' 0.7'); h2b.Color(4)=0.7;  % 30% transparent
h2c = plot(1:5,  15:-1:11, '.-r', 'LineWidth',8, 'DisplayName',' 1.0');  % 100% opaque = 0% transparent

Transparent HG2 plot lines
Transparent HG2 plot lines

Now for the fun part: we can make color-transition (gradient) effects along the line, using its hidden Edge property:

>> h2b.Edge.get
          AlignVertexCenters: 'off'
             AmbientStrength: 0.3
                ColorBinding: 'object'
                   ColorData: [4x1 uint8]
                   ColorType: 'truecoloralpha'
             DiffuseStrength: 0.6
            HandleVisibility: 'off'
                     HitTest: 'off'
                       Layer: 'middle'
                   LineStyle: 'solid'
                   LineWidth: 8
               NormalBinding: 'none'
                  NormalData: []
                      Parent: [1x1 Line]
               PickableParts: 'visible'
    SpecularColorReflectance: 1
            SpecularExponent: 10
            SpecularStrength: 0.9
                   StripData: [1 6]
                     Texture: []
                  VertexData: [3x5 single]
               VertexIndices: []
                     Visible: 'on'
       WideLineRenderingHint: 'software'
>> h2b.Edge.ColorData  %[4x1 uint8]
ans =

The tricky part is to change the Edge.ColorBinding value from its default value of ‘object’ to ‘interpolated’ (there are also ‘discrete’ and ‘none’). Then we can modify Edge.ColorData from being a 4×1 array of uint8 (value of 255 corresponding to a color value of 1.0), to being a 4xN matrix, where N is the number of data points specified for the line, such that each data point along the line will get its own unique RGB or RGBA value. (the data values themselves are kept as a 3xN matrix of single values in Edge.VertexData).
So, for example, let’s modify the middle (30%-transparent) red line to something more colorful:

>> cd=uint8([255,200,250,50,0; 0,50,250,150,200; 0,0,0,100,150; 179,150,200,70,50])
cd =
  255  200  250   50    0
    0   50  250  150  200
    0    0    0  100  150
  179  150  200   70   50
>> set(h2b.Edge, 'ColorBinding','interpolated', 'ColorData',cd)

HG2 plot line color, transparency gradient
HG2 plot line color, transparency gradient

As you can see, we can interpolate not only the colors, but also the transparency along the line.
Note: We need to update all the relevant properties together, in a single set() update, otherwise we’d get warning messages about incompatibilities between the property values. For example:

>> h2b.Edge.ColorBinding = 'interpolated';
Warning: Error creating or updating LineStrip
 Error in value of property ColorData
 Array is wrong shape or size
(Type "warning off MATLAB:gui:array:InvalidArrayShape" to suppress this warning.)


Note how the markers are clearly seen in the transparent lines but not the opaque ones. This is because the markers have the same color as the lines in today’s example. Since the lines are wide, the markers are surrounded by pixels of the same color. Therefore, the markers are only visible when the surrounding pixels are less opaque (i.e., lighter).
As a related customization, we can control whether the markers appear “on top of” (in front of) the line or “beneath” it by updating the Edge.Layer property from ‘middle’ to ‘front’ (there is also ‘back’, but I guess you won’t typically use it). This is important for transparent lines, since it controls the brightness of the markers: “on top” (in front) they appear brighter. As far as I know, this cannot be set separately for each marker – they are all updated together.
Of course, we could always update the line’s fully-documented MarkerSize, MarkerFaceColor and MarkerEdgeColor properties, in addition to the undocumented customizations above.
Next week I will describe how we can customize plot line markers in ways that you never thought possible. So stay tuned 🙂

Categories: Handle graphics, Medium risk of breaking in future versions, Stock Matlab function, Undocumented feature

43 Comments (Open | Close)

43 Comments To "Plot line transparency and color gradient"

#1 Comment By Paul On November 14, 2014 @ 11:28

Have you managed to get the same working for markers? I can’t set the alpha component for MarkerFaceColor, and setting it for Color doesn’t even affect the marker edge:

>> x = plot(X, Y, 'o', 'MarkerFaceColor', [0.5, 0.5, 0.5]);
>> x.Color(4) = 0.1;
>> x.MarkerFaceColor(4) = 0.5;
While setting the 'MarkerFaceColor' property of Line:
Color value must be a 3 element numeric vector 

I’m using 2013b, maybe it’s different in later versions?

#2 Comment By Yair Altman On November 15, 2014 @ 12:29

@Paul – I plan to cover Marker customizations (including transparency) in next week’s post. Stay tuned 🙂

#3 Comment By Yaroslav On November 16, 2014 @ 11:05

That’s absolutely splendid, @Yair!

All those years I used a 2×N mesh in order to make a gradient plot, and it turns out to be so simple in HG2. Keep up the good work!

#4 Pingback By Plot markers transparency and color gradient | Undocumented Matlab On November 19, 2014 @ 09:42

[…] opens up Matlab plots to a whole new spectrum of customizations that were more difficult (although not impossible) to achieve earlier.Throughout today, we’ve kept the default FaceColorType/EdgeColorType […]

#5 Comment By Leslie On February 3, 2015 @ 18:59

Is it possible to set the transparency of 2D contourf plot fills? I used to be able to do this before 2014b, but the latest update broke what I was using. I used allchild to get handles of the subobjects and set the FaceAlpha to less than 1

#6 Comment By Yair Altman On February 4, 2015 @ 00:35

[~, hContour] = contourf(peaks(20), 10);
hFaces = hContour.FacePrims;
for faceIdx = 1 : numel(hFaces)
   hFaces(faceIdx).ColorType = 'truecoloralpha';  % default = 'truecolor'
   hFaces(faceIdx).ColorData(4) = 150;   % default=255

#7 Comment By Leslie On February 4, 2015 @ 08:14

Great, many thanks for this. When I try that code, hFaces comes out as 0x0. When I insert a pause(0.05) before the hFaces = hContour.FacePrims line it works. Strange.

#8 Comment By Yair Altman On February 4, 2015 @ 08:16

I assume that drawnow will also work…

#9 Comment By Leslie On February 4, 2015 @ 08:28

Yes, it does. Thanks again.

#10 Comment By matt dash On February 5, 2015 @ 11:04

This is great, but I find that when i set an alpha for a line color, the line smoothing goes away and i get the old fashioned pixelated lines. Have you noticed that too or is it just me?

#11 Comment By Evaluate On March 4, 2015 @ 13:20

It seems that the workaround doesn’t work on 2014a edition!
I receive “Attempt to reference field f non-structure array.”
Any comments?

#12 Comment By Yair Altman On March 4, 2015 @ 14:49

Of course it doesn’t – as stated in the top paragraph, this article (which is part of a series) only discusses HG2, in other words R2014b and later. R2014a still uses the previous version of HG, which is radically different.

#13 Comment By James On April 21, 2015 @ 12:43

I’ve been able to make some beautiful figures using HG2 thanks to your help. Unfortunately, I am now unable to find a way to export to any sort of vector format that maintains my transparent lines (among other issues). I have tried export_fig, and exporting to .svg. When I do the export, I simply get the figure without my edited properties like alpha and color interpolation. Have you found any way around this? It’s driving me crazy and, from an academic standpoint, appears to make many of the advances of HG2 frustratingly useless. At this point I would put up with just about anything that would get me a super-high resolution image out.

#14 Comment By Yair Altman On April 21, 2015 @ 14:19

@James – try using the opengl (rather than painters) renderer (the ‘-opengl’ parameter in export_fig). Note that this might take a long time, consume much memory, and generate a huge output file.

Also try using bitmap output with a large resolution (the -r# parameter) – it would not be vectorized, but at least it might have a large-enough resolution to be publication quality.

#15 Comment By James On April 22, 2015 @ 05:39

Hi Yair,

Thanks for the quick response. The opengl renderer works for .png or .bmp format, yes, but when I change the resolution the output changes from my pretty figure with transparency, etc. to essentially the plot before I edit any of the color and alpha properties (still not working for vector outputs).

What I’ve gathered so far is that this may be related the necessity of using the drawnow command in between plotting the line and getting the line marker handles. For example, if I do not use drawnow after plotting the line, I am unable to access the line.MarkerHandle properties. I do not need the drawnow to do to things such as changing the grid lines (so documented properties related to the axes rather than the line). When I try to render with vector graphics or .bmp with increased resolution, I get only the changes I made that don’t rely on the drawnow (so it renders the grid lines, but not the color and alpha values based on line.MarkerHandle.EdgeColorData).

I have no current idea how to fix this. I wonder if it has to do with the way the exporter “re-renders” the figure for export, and if it’s as simple as getting it to add another drawnow in there somewhere so that it reads the MarkerHandle changes. I don’t know if export_fig would be able to deal with such a change. I guess any further advice, tips or even a solution would be greatly appreciated.

Thanks again!

#16 Comment By Yair Altman On April 22, 2015 @ 06:10

@James – I suspect that you will find the same behavior with Matlab’s built-in print function, and in this case there is not much that export_fig can do since it uses print internally.

#17 Comment By James On April 22, 2015 @ 09:28

Thanks. I guess these hidden properties are unfortunately still useless when it comes to vector graphics (or even high quality non-vector formats unless you have a high-res display and effectively take a screenshot). Hopefully this gets updated soon.

#18 Comment By Sebastian On June 16, 2015 @ 04:54

Quick comment: on my Computer (Win7, Matlab 2015a) the above syntax only works for lines up to exactly 25000 data points. Also, changing the ColorBinding and setting the ColorData is only possible, if the line has already been drawn. Therefore, it is necessary to issue a drawnow before setting these parameters:

i = 25000;  % Will not work if changed to 25001 (at least on my computer)
h = plot(rand(i,1));
c = uint8(randi(255,4,i));
drawnow % Will not work, if this command is not issued

#19 Comment By Yaroslav On November 20, 2018 @ 14:29

Hi Yair,

There is an issue when there are too many points in the plot as Sebastian [9]. Below 25000 points, everything works as expected:

% define
N   = 25000;
t   = linspace(0,4*pi,N);
x   = 27*cos(t) + 29*cos(27/2*t);
y   = 27*sin(t) - 29*sin(27/2*t);

% plot
hFig  = figure('Units','normalized','Position',[0.2 0.2 0.4 0.5]);
hAxes = axes('XTick',{},'YTick',{},'NextPlot','replacechildren','Box','on');
hPlot = plot(x,y);
axis equal tight;
drawnow(); % as required
hPlot.Edge.ColorBinding = 'interpolated';
hPlot.Edge.ColorData    = [uint8(parula(N)*255) 255*ones(N,1,'uint8')]';

Above this magic number, Matlab tries to optimize the figure by plotting only a subset of the vertices. Repeating the procedure with more points than that results in a warning and no color gradient:

N   = 25001;
hPlot.Edge.ColorData    = [uint8(parula(N)*255) 255*ones(N,1,'uint8')]';
Warning: Error creating or updating LineStrip
 Error in value of property  ColorData
 Array is wrong shape or size 

To fix the issue, we need to probe the number of vertices in hPlot.Edge:

N   = 25001;
N2  = size(hPlot.Edge.VertexData,2);
hPlot.Edge.ColorData = [uint8(parula(N2)*255) 255*ones(N2,1,'uint8')]';

But, if we try, say, to resize the figure, the warning reappears (though the gradient stays):

drawnow(); % just in case...
hFig.Position = [0.2 0.2 0.5 0.6];
Warning: Error creating or updating LineStrip
 Error in value of property  ColorData
 Array is wrong shape or size 

Similar unexpected behavior occurs in zoom, copyobj etc.

P.S, my Matlab version is R2018a, so it looks like a rather persistent problem.

#20 Comment By Moshe On September 5, 2015 @ 13:00

Hi Yair,

I tried to use the code for varying the transparency and for some reason the following example code does not work as expected:

close all
t = linspace(0,2*pi,10);
h = plot(t, sin(t), '-', 'LineWidth',10);
transp = 100*ones(size(t)); %abs(round(cos(t)*255));
transp(1:5) = 200;
newColor = repmat(h.Edge.ColorData, 1, numel(transp));
newColor(4,:) = transp';
newColor = uint8(newColor);
set(h.Edge, 'ColorBinding','interpolated', 'ColorData',newColor);

I expected first 5 points to have transparency of 200 and then 5 with transparency of 100. Can you explain why the result is with same transparency all over ?


#21 Comment By growl On October 13, 2015 @ 13:21

I have the same problem.

I wrote code essentially the same as yours.

newColor(1:3,:) works as expected.

newColor(4,:) does not change transparency.

Not sure how to fix it, but I gave up trying.

#22 Comment By John Thompson On July 16, 2016 @ 03:03

Hello Yair,

Thanks for the useful tip.

I was am having trouble creating a figure with multiple lines and having the color encoding remaining in the plot.

I am plotting multiple lines in a for loop. If I dbstep through each iteration of the loop, then the color will show up, however, when the loop completes the gradient colors go away and the default uniform matlab colors remain. Any suggestions?

example code:

hold on
for i = 1:3
     tractHandle = plot3(tctData{tmpTctID}(:,1),tctData{tmpTctID}(:,2),tctData{tmpTctID}(:,3));
     colorMat = uint8([transpose(tctColor{tmpTctID})*255 ; repmat(aValue,1,size(tctColor{tmpTctID},1))]);
     set(tractHandle.(['ti',num2str(ti)]).Edge, 'ColorBinding', 'interpolated', 'ColorData', colorMat)

#23 Comment By Yair Altman On July 16, 2016 @ 21:12

@John – perhaps after the loop you have some code that causes the axes to repaint and this will cause Matlab to ignore the undocumented color changes. Try to call drawnow at the very end of your plotting section and only then update the handles’ colors to the transparent values.

#24 Comment By davion On July 21, 2016 @ 07:41

Hello, Yair,
I have some problem in using your code to draw a transparent line.
Here are the codes, which are mostly exactly as yours.

cd=uint8([255,200,250,50,0; 0,50,250,150,200; 0,0,0,100,150; 179,150,200,70,50]);
h2b = plot(2:6,  15:-1:11, '.-r', 'LineWidth',8, 'DisplayName',' 0.7'); 
set(h2b.Edge, 'ColorBinding','interpolated', 'ColorData',cd , 'ColorType', 'truecoloralpha');

I wrote it in a script file, but after running it, the output figure is not transparent. I check the properties in h2b.Edge, noticing that the ‘ColorBinding’ is still ‘object’. Then I run the last sentence again in the Command Window, which is shown below.

set(h2b.Edge, 'ColorBinding','interpolated', 'ColorData',cd , 'ColorType', 'truecoloralpha');

And the figure turns to transparent. It is really confusing to me. Could you please tell me how to solve this problem?
PS, the version of my MATLAB is R2015a.

#25 Comment By Jerry On July 21, 2016 @ 08:37

Hello Yair.
I used your code to draw a transparent line. But there are some problems. I wrote the below codes in a .m file.

cd = uint8([255,200,250,50,0; 0,50,250,150,200; 0,0,0,100,150; 179,150,200,70,50]);
h2b = plot(2:6,  15:-1:11, '.-r', 'LineWidth',8, 'DisplayName',' 0.7'); 
set(h2b.Edge, 'ColorBinding','interpolated', 'ColorData',cd , 'ColorType','truecoloralpha');

The codes are almost exactly as yours, except that I set the ‘ColorType’ since it is ‘truecolor’ in default.
However, the line is not a transparent one. I checked the h2b.Edge and found that the ColorBinding is still ‘object’. Then I run the last sentence of the above codes in Command Window again. This time it works and the line is transparent as your results.
Could you please tell me why would this happen and how to fix it? Because I would like to use it to generate some pictures and it’s a disaster if I have to run the last sentence in Command Window each time.
PS, the version of my MATLAB is R2015a.

#26 Comment By Yair Altman On July 21, 2016 @ 10:42

@Jerry – adding drawnow; pause(0.1) after the plot command and before setting the color should solve the problem.

#27 Comment By Jerry On July 22, 2016 @ 04:50

Great, it works. Thanks!
I guess the reason is that when it runs the setting process, the figure is still unfinished?

#28 Comment By Yair Altman On July 22, 2016 @ 09:29


#29 Comment By vince On August 21, 2016 @ 10:35

Is it possible to fade a cluster of points held in two arrays x,y?

h = plot(x,y,'.g')
h.Color(4) = 0.5?

#30 Comment By Yair Altman On September 6, 2016 @ 19:37

@Vince – yes:

hLine = plot(x,y,'.g');
hLine.MarkerHandle.FaceColorType = 'truecoloralpha';  % enable transparency
hLine.MarkerHandle.EdgeColorData(4) = 128;  % 255 = opaque (default), 0 = fully trasparent

#31 Pingback By Colored longitudinal river profiles « TopoToolbox On October 25, 2016 @ 10:53

[…] I came across when reading through Yair Altman’s undocumented MATLAB blog. He reports on some undocumented line properties that were introduced with MATLAB’s new graphics engine in R2014b. I implemented the surface […]

#32 Comment By Tom On December 31, 2016 @ 06:32

Unfortunately it seems that the legend cannot show the corresponding line as a gradient. The line color appears to match one end of the gradient. I tried a bunch of things but wasn’t able to change the lines in the legend to gradients to match the lines in the figure.

#33 Comment By Vlad Atanasiu On July 23, 2017 @ 07:32

Hello Yair,

Do you known if there is an “outline.Color” property for the “line” object? It would make 3D objects much more readable in terms of what is front and what is back (get rid of the Necker illusion). See, e.g., [10]


#34 Comment By Yair Altman On July 23, 2017 @ 08:20

@Vlad – I am not aware of an outline property, but you should be able to replicate it by using two overlapping lines that have different colors/transparency levels, one line slightly wider than the other.

#35 Comment By Vlad Atanasiu On July 25, 2017 @ 00:12

Correct, Yair. But you will have problems where lines meet: their extremities will look disjoined.

#36 Comment By Yair Altman On July 25, 2017 @ 04:20

I don’t think the lines will look disjointed if you ensure that the endpoints are exactly the same.

#37 Comment By M On October 24, 2017 @ 08:28


Is it possible to load the value of transparency and store it in some variable? e.g. x = h2b.Color(4).
I get the error ‘Index exceeds matrix dimensions.’ when I try this. Is there anyway to load this value?


#38 Comment By Yair Altman On October 24, 2017 @ 13:51

You cannot get the transparency component via the Color property, you need to use the line’s edge’s ColorData property instead: x = h2b.Edge.ColorData(4) – this returns a uint8 number between 0-255. You can convert it into a 0-1 double value using (for example) double(h2b.Edge.ColorData(4))/255.

#39 Comment By Sina M. On April 30, 2018 @ 15:32

I would like to define the transparency of a m_contour-plot, meaning the transparency of the contour-line. I have tried it as follows:

[p1, p2] = m_contour(x, y, z, 'color',[0.0 0.5 1.0], 'linewidth',1.5)
hold on
p2.Color(4) = 0.3

This doesn’t work. Is there a possibility to solve that problem?

#40 Comment By Yair Altman On May 8, 2018 @ 14:06

@Sina – you need to access the [11], and then change the lines’ ColorType from ‘truecolor’ to ‘truecoloralpha’, as I explained multiple times on this page.

[c,h] = contour(peaks,'LevelStep',1,'ShowText','on'); drawnow; 
lines = h.EdgePrims;
newColor = uint8([0,0,0,100]');  % 100/255 = 39% transparency
set(lines, 'ColorType','truecoloralpha', 'ColorData',newColor);

#41 Comment By Yoni On May 7, 2018 @ 23:51

I am wondering if anyone else has trouble saving lines made with a color gradient?
Specifically, I am trying to save a vector format (pdf, eps, or similar) with h2b-style multicolor lines. The color gradient lines don’t show up, and other programs (Illustrator) will throw an error when you open the file. Matlab itself has a problem saving to pdf that it doesn’t have with solid lines.
I am looking to get a vector graphic version of one of these figures, any help would be great!

#42 Comment By Ondrej On July 4, 2018 @ 13:09

Hi Yair,

I am trying to plot a line with a gradient which would be “perpendicular” to the line. For example:

N = 10;
p = plot(1:N, ones(1, N), ‘Linewidth’, 20);
cd = [uint8(jet(N)*255) uint8(ones(N, 1))].’;
set(p.Edge, ‘ColorBinding’,’interpolated’, ‘ColorData’,cd)

This is a horizontal line with color gradient going from left to right (in the direction of the sample points). Is there a way to have a gradient going from top to bottom? (if the line is tilted, then the gradient would be still perpendicular to that line). The effect should look like the line is fading out in the perpendicular direction.

Thanks for any hints and ideas.

#43 Comment By albert On January 10, 2019 @ 21:22


Take a look at this function, it fades a plot and add new data on it.

Article printed from Undocumented Matlab: http://undocumentedmatlab.com

URL to article: http://undocumentedmatlab.com/articles/plot-line-transparency-and-color-gradient

URLs in this post:

[1] Backdrop: http://undocumentedmatlab.com/blog/customizing-axes-part-3-backdrop

[2] Baseline: http://undocumentedmatlab.com/blog/customizing-axes-part-2

[3] Plot markers transparency and color gradient : http://undocumentedmatlab.com/articles/plot-markers-transparency-and-color-gradient

[4] Undocumented plot marker types : http://undocumentedmatlab.com/articles/undocumented-plot-marker-types

[5] Plot LineSmoothing property : http://undocumentedmatlab.com/articles/plot-linesmoothing-property

[6] Plot legend customization : http://undocumentedmatlab.com/articles/plot-legend-customization

[7] Accessing hidden HG2 plot functionality : http://undocumentedmatlab.com/articles/hidden-hg2-plot-functionality

[8] Draggable plot data-tips : http://undocumentedmatlab.com/articles/draggable-plot-data-tips

[9] : https://undocumentedmatlab.com/blog/plot-line-transparency-and-color-gradient#comment-351387

[10] : https://en.wikipedia.org/wiki/File:4Asterane.png

[11] : https://undocumentedmatlab.com/blog/customizing-contour-plots

[12] : https://www.mathworks.com/matlabcentral/fileexchange/69816-fadeit

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.