File Exchange

image thumbnail


version (18.7 KB) by Jan
RunLength coding as fast MEX and M-code


Updated 08 Apr 2017

View Version History

View License

RUNLENGTH - Run-length coding
Run-length encoding splits a vector into one vector, which contains the
elements without neighboring repetitions, and a second vector, which
contains the number of repetitions.
This can reduce the memory for storing the data or allow to analyze sequences.
Encoding: [B, N, BI] = RunLength(X)
Decoding: X = RunLength(B, N)
X: Full input signal, row or column vector.
B: Compressed data, neighboring elements with the same value are removed.
B and X have the same types.
N: Number of repetitions of the elements of B in X as DOUBLE or UINT8 row vector.
BI: Indices of elements in B in X as DOUBLE row vector.
RunLength(X, 'byte') replies N as UINT8 vector.

You can find a lot of RLE tools in the FileExchange already. This C-Mex is
about 5 times faster than good vectorized M-versions.
The M-file RunLength_M contains vectorized and loop M-code for education.

Encode and decode:
[b, n] = RunLength([8, 9, 9, 10, 10, 10, 11])
x = RunLength(b, n)
% b = [8,9,10,11], n = [1,2,3,1], x = [8,9,9,10,10,10,11]
Limit counter to 255:
[b, n] = RunLength(ones(1, 257), 'byte')
% b = [1, 1], n = uint8([255, 2])
LOGICAL input:
[b, n] = RunLength([true(257, 1); false])
% b = [true; false], n = [257, 1]
Find the longest sequence:
x = floor(rand(1, 1e6) * 2);
[b, n, bi] = RunLength(x);
[longestRun, index] = max(n);
longestPos = bi(index);

The C-code is compiled automatically the first time RunLength is called.
See "RunLength_ReadMe.txt" for more details.

The unit-test uTest_RunLength tests validity and speed.

Tested: Matlab 6.5, 7.7, 7.8, 7.13, WinXP/32, Win7/64
Compiler: LCC3.8, BCC5.5, OWC1.8, MSVC2008/2010
Does not compile under LCC2.4 shipped with Matlab/32!
Assumed Compatibility: higher Matlab versions, Linux, MacOS.

Cite As

Jan (2021). RunLength (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (34)


@Alaa AH: Downloading the files should run without a problem. The first call of RunLength.m will call InstallMex() automatically with the correct inputs.
I cannot imagine, why randi() is not available on your system. This command belongs to Matlab's standard toolbox functions.

Alaa AH

hanadi abbas

Alaa AH

Hello, please help me solve this problem. When I download the InstallMex file, I see the following MATLAB error
??? Input argument "SourceFile" is undefined.

Error in ==> InstallMex at 88
if ~ ischar (SourceFile)
Also, when executing the uTest_RunLength file, an error appears
??? Undefined function or method 'randi' for input arguments of type 'double'.

Error in ==> uTest_RunLength at 167
x0 = myCast (randi ([0,1], 1000, 1), aType);
what should I do

chou fly


@Athira Gopinath: Did you install a C compiler and run "mex -setup" already? If so, which compiler do you use? Please send me the complete output of "mex -O -v RunLength.c" by mail - you find the address inside the code. Without a C compiler, you cannot create the C-mex file, but the Matlab version RunLength_M().
I'm not sure what "Error in comp (line 1)" means.

Athira Gopinath

While I tried to execute the code,it shows installation error-Error using RunLength (line 72)
Installation failed.Also, Error in comp (line 1)
[b, n] = RunLength([8, 9, 9, 10, 10, 10, 11]).Please revert me back if you find any solution.

Jerome Garnier-Brun


@wen-feng Huang: This is correct. The C-Mex file considers the real part only. I will implement an error message, if it is called with complex input.

wen-feng Huang

Thank you for the great work. BTW, it seems that the C-mex file has different result from the M-file when input vector contains complex numbers.


@Katy: Do not store user-defined files inside the programs base directory in C:\Program Files\MATLAB. You need to work with admin privileges to do so, and this can cause further troubles. Use a user-defined folder, e.g. inside your Documents folder and add it to your path (see Matlab command: pathtool). If you store the M-files and the downloaded pre-compiled Mex file there, everything should work. Store the mexw64 file exactly where the M-files are saved.
Of course you cannot double-click the compiled C-mex file. Moving it to the "Matlab folder" will not work and is a bad idea, see above.
I have no idea why downloading the MinGW-C-compiler fails and I cannot control this. But if you open the list of supported compilers:
and click on the "MinGW 4.9.2" link, you enter:
On the top there is the explanation of a problem, see
This bug report contains the detailed description of a workaround. This is complicated, and therefore I offered to download the pre-compiled MEX files.

Katy Weihrich

I need this function to run a code from a former colleague. However, I have got some problems downloading it correctly.

After Downloading WinRAR opens automatically. I then unzipped the files into the Matlab folder (C:/Program Files/MATLAB/R2015b). When I then try to run the example code, I get an error message stating:

"Compile: C:\Program Files\MATLAB\Runlength\RunLength.c
mex -O -largeArrayDims -D_LITTLE_ENDIAN -DHAS_HG2 -DMATLABVER=806 RunLength.c
*** Compilation failed:
No supported compiler or SDK was found. You can install the freely available MinGW-w64 C/C++ compiler; see Install MinGW-w64 Compiler. For more options, see"
followed by a long section where Matlab is looking for different versions or parts of a 'Intel C++ Composer XE 2011 with Microsoft SDK 7.1 (C)' complier.
and at last the message
"The compilation failed! Possible solutions:
* Is a compiler installed and set up properly by: mex -setup?
* Try to compile manually:
cd('C:\Program Files\MATLAB\Runlength')
mex -O -largeArrayDims -D_LITTLE_ENDIAN -DHAS_HG2 -DMATLABVER=806 RunLength.c -v
* Or download the pre-compiled file RunLength.mexw64:
* Please send this report to the author.
== InstallMex: failed."

Then i tried running the command "InstallMex('RunLength.c')" but got the same error message again.
Then i downloaded the RunLength.mexw64 file from I could not open it by dopple klick, so I moved the file to the Matlab folder and tried running the function again. Got the same result.

Then I looked up the error message and decided to try to download a C++ Complier.
Trying to download the MinGW-w64 C/C++ Compile on failed to download. i got a " Download Failed: Received fatal alert: protocol_version" error message.

I am out of my options now. Did someone come across this problem before and can help me?


@lou ham: Please ask this in the Answers forum and post some example data with input and output.

lou ham

hi, how embedding caracter @ inside resulting vector

Ameer Hamza

Andreas Wunsch

mak khatib

Zhang Liang

Excellent job! Why not put it on Github for better reviewing?

Zhang Liang

Steven Hall

Alyssa Gutierrez

haithem abdelghany

thank you i get it


@haithem abdelghany: I do not understand the question.

haithem abdelghany

hi plz i using the code for dicom compression bit it do not
Is it not supported



@cyclist: This was a lazy choice without intention. I will adjust this in the next days and implement a faster way to obtain the indices BI. Thanks for this suggestion.

the cyclist

Very useful utility that I use pretty often, and recommend regularly on the Answers forum.

Now that MATLAB has implemented implicit expansion, I have had unexpected behavior because b is Nx1 (for input x with N runs), while n and bi are 1xN. Is there a reason for that choice?

Benny Lifschitz

just what I was looking for!
very well documented and easy to use

Mario Koddenbrock

Richard Johnson

Excellent. Well commented. Lots of input checking. Variable naming could be better, but people probably say that about my code.


Thanks for the comments, Oleg. I'm going to enhance InstallMex to let a dialog box appear to let the user decide, if this is worth a warning or an error.

The 2nd input N was thought to be created by a former call to RunLength with 1 input argument. But there is actually no good reason to restrict the types of the 2nd input. It is only inconvenient to care about all different types of inputs inside the C-Mex: The only efficient approach is to create a subfunction for each type, because an internal conversion must consider e.g. overflows of UINT64 data when converted to DOUBLE. So I decided to let the user decide if "RunLength(B, double(N))" is sufficient. But for (U)INT16/32 this problem cannot occur and three extra lines of code are sufficient. Therefore I will add this in the next version.

Oleg Komarov

An additional comment, is there any reason why the second input cannot be uint16, uint32 or single?

Oleg Komarov

I have been using Urs' milestone for years now and I am pleasantly making the switch to this superb contribution.

RunLength decoding/encoding as fast as it gets!

Also, thanks to InstallMex that is bundled with Jan's submissions, it's a no brainer.

InstallMex errors if a binary is on the some Matlab's path already. However, sometimes I just want to compile for a local project. Maybe the error could be switched to a warning?


Sorry, the first submission missed the file . A new version is submitted already. Please feel free to contact me, if the compilation of a file does not work.

MATLAB Release Compatibility
Created with R2011b
Compatible with any release
Platform Compatibility
Windows macOS Linux

Inspired: runindex, FillGaps_ez

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!