% mergeDetections - Merge detections into clustered detections
% 
%    clusteredDetections = mergeDetections(detections, clusterIdx) merges
%    detections sharing the same cluster labels. By default, the function
%    merges detections in the same cluster using a Gaussian mixture merging
%    algorithm. The function assumes that all detections in the same
%    cluster share the same Time, SensorIndex, ObjectClassID,
%    MeasurementParameters, and ObjectAttributes.
% 
%    detections is one of the following:
%
%    * A cell array of objectDetection objects
%    * An array of objectDetection objects
%    * A struct array with same fields as properties of objectDetection
%
%    clusterIdx is a vector with the same number of elements as the
%    detections. clusterIdx(i) is the cluster label for i-th detection.
% 
%    clusteredDetections are the clustered detections. The number of
%    elements in clusteredDetections is equal to the number of unique
%    labels in the input, clusterIdx. The format of the clusteredDetections
%    is the same as input detections.
% 
%    clusteredDetections = mergeDetections(..,'MergingFcn',mergeFcn)
%    specifies a function for merging detections sharing the same cluster
%    index.
%
%    mergeFcn must have one of the following signatures:
% 
%    1. Detection input and output
%       detectionOut = mergeFcn(detectionsIn) 
% 
%       detectionsIn is a cell array of objectDetection objects in the same
%       cluster. 
%
%       detectionOut is a scalar objectDetection object representing the
%       merged detection.
% 
%    2. Mean and Covariance input and output
%       [mergedMean, mergedCovariance] = mergeFcn(means, covariances)
% 
%       means is an M-by-N matrix representing measurements in the cluster.
%       M is the size of the input measurement and N is the number of
%       measurements in the cluster.
% 
%       covariances is an M-by-M-by-N matrix representing the associated
%       uncertainty covariance matrix. 
% 
%       mergedMean is a P-by-1 vector representing the merged measurement.
%       Note that the size of the merged measurement (P) may or may not be
%       same as the size of the input measurement (M). This allows you to
%       merge many detections into parameterized forms such as rectangular
%       or cuboid detections.
%
%       mergedCovariance is a P-by-P vector representing the uncertainty
%       covariance in the merged measurement.
% 
%    Note: You can use covariance fusion functions such as fusexcov,
%    fusecovint and fusecovunion in the Sensor Fusion and Tracking Toolbox
%    as MergingFcn.
% 
%    Example: Create clusters from positional detections in Rectangular frame
%    % Generate 10 detections from 2 clusters with 2 false alarms
%    x1 = [5;5;0] + randn(3,4); % 4 detections in cluster 1
%    x2 = [5;-5;0] + randn(3,4); % 4 detections in cluster 2
%    xFalse = 30*randn(3,2); % 2 false alarms
%    x = [x1 x2 xFalse];
%
%    % Assemble as objectDetection array
%    detections = repmat({objectDetection(0,[0;0;0])},10,1);
%    for i = 1:10
%      detections{i}.Measurement = x(:,i);
%    end
%
%    % Define cluster index according to the scenario defined above. This
%    % is typically obtained by a clustering algorithm
%    clusterIndex = [1;1;1;1;2;2;2;2;3;4]; 
% 
%    clusteredDetections = mergeDetections(detections, clusterIndex);
% 
%    % Visualize the results
%    tp = theaterPlot;
%
%    % Colors for plotters
%    clrs = lines(2);
%
%    % Unclustered detection plotter
%    detPlotterUn = detectionPlotter(tp,...
%                 'DisplayName','Unclustered Detections',...
%                 'MarkerFaceColor',clrs(1,:),...
%                 'MarkerEdgeColor',clrs(1,:));
%
%    % Clustered detection plotter
%    detPlotterC = detectionPlotter(tp,...
%                 'DisplayName','Clustered Detections',...
%                 'MarkerFaceColor',clrs(2,:),...
%                 'MarkerEdgeColor',clrs(2,:));
% 
%    % Concatenate measurements and covariances from unclustered detections
%    detArray = [detections{:}];
%    xUn = horzcat(detArray.Measurement)';
%    PUn = cat(3,detArray.MeasurementNoise);
% 
%    % Plot unclustered measurements with covariances
%    plotDetection(detPlotterUn,xUn,PUn);
%
%    % Concatenate measurements and covariance from clustered detections
%    clusteredDetArray = [clusteredDetections{:}];
%    xC = horzcat(clusteredDetArray.Measurement)';
%    PC = cat(3,clusteredDetArray.MeasurementNoise);
% 
%    % Plot clustered detections
%    plotDetection(detPlotterC,xC,PC);
%
%    See also: objectDetection, theaterPlot

 
% Copyright 2021-2022 The MathWorks, Inc.

