Code covered by the BSD License  

Highlights from
RunLength

image thumbnail

RunLength

by

 

21 May 2013 (Updated )

RunLength coding as fast MEX and M-code

RunLength(varargin)
function [out1, out2] = RunLength(varargin)
% RUNLENGTH - Run-length en- and decoding
% 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 analyse sequences.
%
% Encoding: [B, N, BI] = RunLength(X)
% Decoding: X          = RunLength(B, N)
% INPUT / OUTPUT:
%   X:  Full input signal, row or column vector.
%       Types: (U)INT8/16/32/64, SINGLE, DOUBLE, LOGICAL, CHAR.
%   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. Sequences with more than 255
% elements are split into parts. This needs less memory and processing time.
%
% NOTES:
%   The comparison treats NaNs as equal.
%   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.
%
% EXAMPLES:
% 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);
%
% COMPILATION:
% Run this function once to compile the MEX file. Alternative method are
% explained in RunLength.c .
% Run the unit-test uTest_RunLength to test 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 Matlab6.5!
% Assumed Compatibility: higher Matlab versions, Linux, MacOS.
%
% Author: Jan Simon, Heidelberg, (C) 2013 j@n-simon.de

% $JRev: R-i V:008 Sum:Mhojop2sbDWj Date:17-Sep-2013 00:46:17 $
% $License: BSD (use/copy/change/redistribute on own risk, mention the author) $
% $UnitTest: uTest_RunLength $
% $File: Tools\GLMath\RunLength.m $
% History:
% 001: 23-Mar-2013 00:45, First version.
% 002: 29-Mar-2013 23:36, 3rd output BI for encoding.

% Initialize: ==================================================================
% Do the work: =================================================================
% This is a dummy code only, which compiles the C-function automatically:
Ok = InstallMex('RunLength.c', 'uTest_RunLength');
if ~Ok
   error('JSimon:RunLength:BadCompilation', 'Compilation failed.');
end

if nargout == 1
   out1         = RunLength(varargin{:});
else
   [out1, out2] = RunLength(varargin{:});
end

% return;

Contact us