Annotations

class core.Annotations

Bases: matlab.mixin.Copyable

ANNOTATIONS - Annotations class is responsible for keeping annotations of the model.

Constructor Summary
Annotations()

ANNOTATIONS - Constructor for the Annotations class.

Syntax:
obj = core.Annotations()

Constructor for the Annotations class. Create a new instance of the class with default parameters

Input Arguments:

Output Arguments:

obj - instance of the Annotations class.

Property Summary
defaultAnnotationText

a matrix with coordinates of the labels [pointIndex, z x y t]

defaultAnnotationValue

default text for the annotations

labelPosition

an array with values for labels

labelText
labelValue

a cell array with labels

Method Summary
addLabels(labels, positions, values)

ADDLABELS - Add labels with positions to the class.

Syntax:
obj.addLabels(labels, positions, values)
Input Arguments:

  • labels - a cell array with labels

  • positions - a matrix with coordinates of the labels [pointIndex, z x y t]

  • values - an array of numbers with values for the labels [@em optional], default = 1

Output Arguments:

Usage:

Example 1

labels{1} = 'my label 1';
labels{2} = 'my label 2';
positions(1,:) = [50, 75, 1, 3];% position 1: z=1, x=50, y=75, t=3;
positions(2,:) = [50, 75, 2, 5];% position 1: z=2, x=50, y=75, t=5;

Example 2

obj.mibModel.I{obj.mibModel.id}.annotations.addLabel(labels, positions);% add a labels to the list, call from mibController

Example 3

addLabel(obj, labels, positions);% Call within the class;  add a labels to the list
clearContents()

CLEARCONTENTS - Set all elements of the class to default values.

Syntax:
obj.clearContents()

Input Arguments:

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.annotations.clearContents();

Example 2

clearContents(obj);% Call within the class
crop(cropF)

CROP - Recalculation of annotation positions during image crop.

Syntax:
obj.crop(cropF)
Input Arguments:

  • cropF - a vector [x1, y1, dx, dy, z1, dz, t1, dt] with parameters of the crop. Note! The units are pixels! Parameters t1 and dt are optional!

Usage:

Example 1

cropF = [100 512 200 512 5 20 7 15];% define parameters of the crop

Example 2

cropF2 = [100 512 NaN NaN 5 NaN 7 NaN];% alternative definition of parameters for the crop

Example 3

obj.mibModel.I{obj.mibModel.id}.annotations.crop(cropF);% adjust coordinates due to cropping

Attention: parameters dx, dy, dz, dt are not used, so they can be replaced with NaNs

getCurrentSliceLabels()

GETCURRENTSLICELABELS - [labelsList, labelValues, labelPositions, indices] = getCurrentSliceLabels(obj).

Syntax:
[labelsList, labelValues, labelPositions, indices] = obj.getCurrentSliceLabels()

Get list of labels shown at the current slice

Note: replaced with mibImage.getSliceLabels

Input Arguments:

Output Arguments:

  • labelsList - a cell array with labels

  • labelPositions - a matrix with coordinates of the labels [labelIndex, z x y t]

  • indices - indices of the labels

Usage:

Example 1

[labelsList, labelPositions, indices] = LabelsInstance.getCurrentSliceLabels();% get all labels from the currently shown slice

Example 2

[labelsList, labelPositions, indices] = getCurrentSliceLabels(obj);% Call within the class;  get all labels from the currently shown slice
getLabels(rangeZ, rangeX, rangeY, rangeT)

GETLABELS - Get list of labels.

Syntax:
[labelsList, labelValues, labelPositions, indices] = obj.getLabels(rangeZ, rangeX, rangeY, rangeT)
Input Arguments:

  • rangeZ - (optional) define range of labels to retrieve for Z [minZ maxZ], can be NaN

  • rangeX - (optional) define range of labels to retrieve for X [minX maxX], can be NaN

  • rangeY - (optional) define range of labels to retrieve for Y [minY maxY], can be NaN

  • rangeT - (optional) define range of labels to retrieve for T [minT maxT], can be NaN

Output Arguments:

  • labelsList - a cell array with labels

  • labelValues - an array of numbers with values

  • labelPositions - a matrix with coordinates of the labels [labelIndex, z x y t]

  • indices - indices of the labels

Usage:

Example 1

[labelsList, labelValues, labelPositions, indices] = obj.mibModel.I{obj.mibModel.id}.annotations.getLabels();% get all labels

Example 2

[labelsList, labelValues, labelPositions, indices] = obj.mibModel.I{obj.mibModel.id}.annotations.getLabels(50);% get all labels from slice 50

Example 3

[labelsList, labelValues, labelPositions, indices] = obj.mibModel.I{obj.mibModel.id}.annotations.getLabels(obj, 50);% Call within the class;  get all labels from slice 50
getLabelsById(labelId)

GETLABELSBYID - Get labels using labelId.

Syntax:
[labels, values, positions, indices] = obj.getLabelsById(labelId)
Input Arguments:

  • labelId - a variable or a vector with a label to retrieve:

    • a single number or a column of numbers - get label that has index equal to the number

    • a matrix - get all labels that have coordinates specified in the matrix [labelIndex, z x y t]

    • a cell array - get all labels that have text specified in the cell array

Output Arguments:

  • labels - - cell array with labels of annotations

  • values - - array with values of annotations

  • positions - - a matrix with coordinates (index; z,x,y,t)

  • indices - - array with indices of annotations

Usage:

Example 1

labelIds = [5, 7, 10]';
[labels, values, positions, id] = obj.mibModel.I{obj.mibModel.id}.annotations.getLabelsById(labelIds);% call from mibController, get labels with indices 5, 7, 10
getLabelsNumber()

GETLABELSNUMBER - Get total number of labels.

Syntax:
labelsNumber = obj.getLabelsNumber()

Input Arguments:

Output Arguments:

  • labelsNumber - a number of labels

Usage:

Example 1

labelsNumber = obj.mibModel.I{obj.mibModel.id}.annotations.getLabelsNumber();% get number of labels

Example 2

labelsNumber = getLabelsNumber(obj);% Call within the class;  get number of labels
getMaxValueZ()

GETMAXVALUEZ - Find and return the maximum Z value for all annotations, as well as their indices.

Syntax:
[maxZ, labelIds] = obj.getMaxValueZ()

Input Arguments:

Output Arguments:

  • maxZ - value of max Z for all annotations

  • labelIds - indices of those annotations

getMinValueZ()

GETMINVALUEZ - Find and return the minimum Z value for all annotations, as well as their indices.

Syntax:
[minZ, labelIds] = obj.getMinValueZ()

Input Arguments:

Output Arguments:

  • minZ - value of min Z for all annotations

  • labelIds - indices of those annotations

getSliceLabels(handles, sliceNumber, timePoint)

GETSLICELABELS - [labelsList, labelValues, labelPositions, indices] = getSliceLabels(obj, handles, sliceNumber, timePoint).

Syntax:
[labelsList, labelValues, labelPositions, indices] = obj.getSliceLabels(handles, sliceNumber, timePoint)

Get list of labels shown at the specified slice

Input Arguments:

  • handles - a handles structure of im_browser

  • sliceNumber - (optional), a slice number to get labels

  • timePoint - (optional), a time point to get the labels

Output Arguments:

  • labelsList - a cell array with labels

  • labelPositions - a matrix with coordinates of the labels [labelIndex, z x y]

  • indices - indices of the labels

Usage:

Example 1

[labelsList, labelPositions, indices] = obj.mibModel.I{obj.mibModel.id}.annotations.getSliceLabels(handles, 15);% get all labels from the slice 15

Example 2

[labelsList, labelPositions, indices] = getSliceLabels(obj, handles);% Call within the class;  get all labels from the currently shown slice
loadAnnotations(filename, options)

LOADANNOTATIONS - Load annotations from a file, replacing the current set.

Syntax:
result = obj.loadAnnotations(filename, options)
Input Arguments:

  • filename - (optional) full path to file; when empty or missing, a file-selection dialog is shown

  • options - (optional) struct with additional parameters:

    • .parentFigure - handle to parent UIFigure for dialogs (required for the CSV column-mapping dialog)

    • .currentDirectory - starting directory for the file-selection dialog; default ''

    • .boundingBox - [x1 width y1 height z1 depth] bounding box for Amira coordinate conversion

    • .pixSize - MIB pixSize struct (.x .y .z) for Amira coordinate conversion

    • .currentT - current time point; used when the file stores only 3-column positions; default 1

Output Arguments:

  • result - 1 on success, 0 if cancelled or failed

Usage:

Example 1 - show file dialog, pass image metadata for coordinate conversion:

options.parentFigure     = obj.view.gui;
options.currentDirectory = obj.mibModel.currentDirectory;
options.boundingBox      = obj.mibModel.I{id}.image.boundingBox;
options.pixSize          = obj.mibModel.I{id}.image.pixSize;
options.currentT         = obj.mibModel.I{id}.slices{5}(1);
result = obj.mibModel.I{id}.annotations.loadAnnotations([], options);

Example 2 - load directly from a known .ann file:

result = obj.mibModel.I{id}.annotations.loadAnnotations('/path/to/file.ann');
removeLabels(labels)

REMOVELABELS - removeLabels(obj, labels).

Syntax:
obj.removeLabels(labels)

Remove specified labels

Input Arguments:

  • labels - (optional) a variable or a vector with a label to remove:

    • omitted - remove all labels

    • a single number or a column of numbers - remove label that has index equal to the number

    • a matrix - remove all labels that have coordinates specified in the matrix [labelIndex, z x y t]

    • a cell array - remove all labels that have text specified in the cell array

Usage:

Example 1

labels{1} = 'my label 1';

Example 2

obj.mibModel.I{obj.mibModel.id}.annotations.removeLabels(labels);% remove annotations that match labels

Example 3

removeLabels(obj, labels);% Call within the class; remove annotations that match labels
renameLabels(oldLabel, newLabelText)

RENAMELABELS - Rename specified labels with new text.

Syntax:
result = obj.renameLabels(oldLabel, newLabelText)
Input Arguments:

  • oldLabel - a variable or a vector with an old label to be renamed:

    • a single number or a column of numbers - rename the label with this index

    • a matrix - rename all labels that have coordinates specified in the matrix [labelIndex, z x y t]

    • a cell array - rename all labels that have text specified in the cell array

  • newLabelText - a cell or a char string with new text for the label

Output Arguments:

  • result - result of the function work: 1 = success, 0 = failure

Usage:

Example 1

oldLabelId = [5, 7, 10]';
label{1} = 'my label 1';

Example 2

obj.mibModel.I{obj.mibModel.id}.annotations.renameLabels(oldLabelId, label);% call from mibController, rename labels with indices 5, 7, 10
replaceLabels(labels, positions, values)

REPLACELABELS - replaceLabels(obj, labels, positions, values).

Syntax:
obj.replaceLabels(labels, positions, values)

Replace existing labels with a new list of labels and their values

Input Arguments:

  • labels - a cell array with labels

  • positions - a matrix with coordinates of the labels [pointIndex, z x y t]

  • values - an array of numbers with values of the labels, (optional) default = 1

Usage:

Example 1

labels{1} = 'my label 1';
labels{2} = 'my label 2';
positions(1,:) = [1, 50, 75, 5];% position 1: x=50, y=75, z=1,t=5;
positions(2,:) = [2, 50, 75, 6];% position 1: x=50, y=75, z=2, t=6;

Example 2

obj.mibModel.I{obj.mibModel.id}.annotations.replaceLabels(labels, positions);% replace labels with a new list

Example 3

replaceLabels(obj, labels, positions);% Call within the class; replace labels with a new list
saveToFile(filename, options)

SAVETOFILE - save Annotations to a file.

Syntax:
obj.saveToFile(filename, options)
Input Arguments:

  • filename - full path to output file

  • options - (optional) struct with saving parameters:

    • .format - (char) output file format:

      • 'ann' - MIB annotation format

      • 'landmarksAscii' - Amira landmarks in ASCII format

      • 'landmarksBin' - Amira landmarks as binaries

      • 'psi' - PSI format ASCII

      • 'xls' - Microsoft Excel format

    • .showWaitbar - (optional) logical; 1 = show, 0 = hide; requires .mibGUI

    • .mibGUI - (optional) handle to the main app UIFigure, required when showWaitbar=1

    • .outputDir - (optional) output directory

    • .convertToUnits - (optional) logical; convert pixel coordinates to physical units; requires .boundingBox and .pixSize

    • .boundingBox - matrix [x1 width y1 height z1 depth], required for unit conversion

    • .pixSize - MIB struct with pixel sizes

    • .labelText - (optional) override obj.labelText with provided cell array

    • .labelPosition - (optional) override obj.labelPosition with provided matrix

    • .labelValue - (optional) override obj.labelValue with provided array

    • .sliceNames - (optional) cell array with filenames, used for Excel and CSV export

    • .addLabelToFilename - (optional) logical; append annotation label to filename; default false

sortLabels(sortBy, direction)

SORTLABELS - Resort the list of annotation labels.

Syntax:
obj.sortLabels(sortBy, direction)
Input Arguments:

  • sortBy - (optional) [char] field to be used for sorting; allowed values:

    • 'name' - sort by the label name (default)

    • 'value' - sort by value

    • 'x' - sort by the X coordinate

    • 'y' - sort by the Y coordinate

    • 'z' - sort by the Z coordinate

    • 't' - sort by the T coordinate

  • direction - (optional) [char] sorting direction; allowed values:

    • 'ascend' - sort in ascending order (default)

    • 'descend' - sort in descending order

Example 1 - sort the list by the label name:

obj.mibModel.I{obj.mibModel.id}.annotations.sortLabels();

Example 2 - sort the list by the label name in descending order:

obj.mibModel.I{obj.mibModel.id}.annotations.sortLabels('name', 'descend');
updateLabels(oldLabel, newLabelText, newLabelPos, newLabelValues)

UPDATELABELS - Update specified labels with newLabels.

Syntax:
result = obj.updateLabels(oldLabel, newLabelText, newLabelPos, newLabelValues)
Input Arguments:

  • oldLabel - a variable or a vector with an old label to be updated:

    • a single number or a column of numbers - update the label with this index

    • a matrix - update all labels that have coordinates specified in the matrix [labelIndex, z x y t]

    • a cell array - update all labels that have text specified in the cell array

  • newLabelText - a cell or a char string with new text for the label

  • newLabelPos - coordinates of the new label [z, x, y]

  • newLabelValues - (optional) an array of numbers with values of the labels, default = 1

Output Arguments:

  • result - result of the function work: 1 - good, 0 - bad

Usage:

Example 1

label{1} = 'my label 1';
newPosition(1,:) = [50, 75, 1, 5];% position 1: x=50, y=75; z=1, t=5

Example 2

obj.mibModel.I{obj.mibModel.id}.annotations.updateLabels(label, label, newPosition);% call from mibController, update coordinates of a label that has "my label 1" text