ContrastNormalization¶

class controllers.ContrastNormalization¶

Bases: handle

CONTRASTNORMALIZATION - Controller for slice-by-slice contrast normalization of 3D/4D datasets.

Normalizes image contrast across Z-slices or time frames using one of four strategies: full-frame Z-stack, time-series, masked-area, or background shift. Fully compatible with the MIB3 batch-processing pipeline (BatchOpt).

Usage:

obj.mibController.startController('controllers.ContrastNormalization');
controllers.ContrastNormalization(mibModel, [], BatchOpt);   % headless batch run
controllers.ContrastNormalization(mibModel, [], NaN);        % return BatchOpt schema
obj.startController('controllers.ContrastNormalization');    % start from MibController
obj.startController('controllers.ContrastNormalization');    % start from MibController

Constructor Summary

ContrastNormalization(mibModel, varargin)¶

CONTRASTNORMALIZATION - Construct the contrast-normalization controller.

Syntax:

obj = controllers.ContrastNormalization(mibModel)
obj = controllers.ContrastNormalization(mibModel, [])
obj = controllers.ContrastNormalization(mibModel, [], BatchOptInput)
obj = controllers.ContrastNormalization(mibModel, [], NaN)

Input Arguments:

• mibModel - handle to models.MibModel.

• varargin{1} (optional) - reserved compatibility slot.

• varargin{2} (optional) - BatchOpt struct for headless run, or NaN to return the default BatchOpt schema via SyncBatch.

Property Summary

BatchOpt¶

structure compatible with batch processing

listener¶

cell array of listener handles

mibModel¶

handle to MibModel

view¶

handle to the ContrastNormalizationGUI .mlapp (empty in batch mode)

Method Summary

static ViewListner_Callback2(~, evnt)¶

VIEWLISTNER_CALLBACK2 - Static guarded listener callback.

Syntax:

obj.ViewListner_Callback2(src, evnt)

Routes UpdateGuiWidgets and NewDataset model events to updateWidgets(). Deletes stale listeners when the controller or its view has been destroyed.

Input Arguments:

• obj - controllers.ContrastNormalization instance.

• evnt - event data from the model.

addCallbacks()¶

ADDCALLBACKS - Wire every widget to the central gui_Callbacks() dispatcher.

Syntax:

obj.addCallbacks()

Sets CloseRequestFcn on the figure, then assigns the gui_Callbacks anonymous handle to every tagged widget listed in the view contract. Widgets not yet present in the .mlapp are silently skipped.

closeWindow()¶

CLOSEWINDOW - Close the dialog, save settings, and release listeners.

Syntax:

obj.closeWindow()

collectSliceStats(z1, z2, t, colorCh, useMask, options)¶

COLLECTSLICESTATS - Compute per-slice mean and std for one color channel.

Syntax:

[mean_val, std_val] = obj.collectSliceStats(z1, z2, t, colorCh, useMask, options)

Iterates over slices z1:z2 at time point t and computes mean and standard deviation of pixel intensities. When useMask is true, statistics are restricted to the pixels flagged by obj.BatchOpt.MaskLayer ('selection' or 'mask'). Slices where the mask is empty return NaN; the caller is responsible for gap-filling.

Input Arguments:

• obj - controllers.ContrastNormalization instance.

• z1 - first slice index (1-based).

• z2 - last slice index (1-based).

• t - time-point index.

• colorCh - scalar color-channel index.

• useMask - logical; true to restrict stats to the mask layer.

• options - struct passed to getData2D; must contain .id.

Output Arguments:

• mean_val - [maxZ x 1] double vector; NaN for empty-mask slices.

• std_val - [maxZ x 1] double vector; NaN for empty-mask slices.

continueBtn_Callback(useBatchMode)¶

CONTINUEBTN_CALLBACK - Validate, back up, and dispatch to the target-specific normalization method.

Syntax:

obj.continueBtn_Callback()
obj.continueBtn_Callback(useBatchMode)

Checks preconditions (virtual mode, indexed color type, mask presence), creates a backup for single-frame operations, then dispatches to the appropriate low-level normalization method based on obj.BatchOpt.Target. On completion the image is re-displayed and the batch controller is notified.

Input Arguments:

• useBatchMode (optional) - logical; true when invoked via the batch processor (no GUI). Default false.

gui_Callbacks(source, event)¶

#ok<INUSD> GUI_CALLBACKS - Dispatcher for every ContrastNormalization widget callback.

Syntax:

obj.gui_Callbacks(source, event)

Routes by source.Tag to the appropriate action method. Target and Mode cases also update context-sensitive widget enable states. All other widgets fall through to updateBatchOptFromGUI().

Input Arguments:

• obj - controllers.ContrastNormalization instance.

• source - widget handle that fired the event.

• event - event data (unused).

normalizeBackground(colorChannel, options)¶

NORMALIZEBACKGROUND - Shift each slice based on masked background intensity.

Syntax:

obj.normalizeBackground(colorChannel, options)

For each color channel, computes the per-slice mean intensity restricted to pixels in the mask layer (representing background regions), fills gaps where the mask is empty, and then shifts each slice so that its background mean matches a common target value. Standard deviation is not used; only a shift is applied.

Input Arguments:

• obj - controllers.ContrastNormalization instance.

• colorChannel - [1 x N] vector of color-channel indices to process.

• options - struct with fields:

  • .id - dataset index.

  • .t - [tVal tVal] time-point pair.

  • .waitbar - handle to the uiprogressdlg; may be [].

  • .waitbarOffset - base progress value before this target starts.

  • .totalSteps - total steps for the waitbar denominator.

  • .parentFig - parent figure for error dialogs.

normalizeMaskedArea(colorChannel, options)¶

NORMALIZEMASKEDAREA - Normalize contrast using per-slice masked-area statistics.

Syntax:

obj.normalizeMaskedArea(colorChannel, options)

For each color channel, computes the per-slice mean and standard deviation restricted to pixels in the mask layer, fills any gaps where the mask is empty, then shifts and scales each slice to match a common target mean and std.

Input Arguments:

• obj - controllers.ContrastNormalization instance.

• colorChannel - [1 x N] vector of color-channel indices to process.

• options - struct with fields:

  • .id - dataset index.

  • .t - [tVal tVal] time-point pair.

  • .waitbar - handle to the uiprogressdlg; may be [].

  • .waitbarOffset - base progress value before this target starts.

  • .totalSteps - total steps for the waitbar denominator.

  • .parentFig - parent figure for error dialogs.

normalizeTimeSeries(colorChannel, options)¶

NORMALIZETIMESERIES - Normalize contrast across time frames.

Syntax:

obj.normalizeTimeSeries(colorChannel, options)

For each color channel, computes mean and standard deviation per time frame (either from the currently shown 2D slice or from the full 3D stack), then shifts and scales each frame so that its statistics match the dataset-wide (or manually specified) target values.

Input Arguments:

• obj - controllers.ContrastNormalization instance.

• colorChannel - [1 x N] vector of color-channel indices to process.

• options - struct with fields:

  • .id - dataset index.

  • .t1 - first time-frame index.

  • .t2 - last time-frame index.

  • .currentZ - Z-slice index for 'Based on current 2D slice' mode.

  • .waitbar - handle to the uiprogressdlg; may be [].

  • .waitbarOffset - base progress value before this target starts.

  • .totalSteps - total steps for the waitbar denominator.

normalizeZStack(colorChannel, options)¶

NORMALIZEZSTACK - Normalize contrast across Z-slices of a single time point.

Syntax:

options = obj.normalizeZStack(colorChannel, options)

For each color channel, computes the per-slice mean and standard deviation over the full image frame and adjusts each slice so that its mean matches the dataset-wide (or manually specified) mean and its spread matches the dataset-wide std.

Input Arguments:

• obj - controllers.ContrastNormalization instance.

• colorChannel - [1 x N] vector of color-channel indices to process.

• options - struct with fields:

  • .id - dataset index.

  • .t - [tVal tVal] time-point pair for the single frame.

  • .waitbar - handle to the uiprogressdlg; may be [].

  • .waitbarOffset - base progress value before this target starts.

  • .totalSteps - total number of (channel × slice) steps for the waitbar.

returnBatchOpt(BatchOptOut)¶

RETURNBATCHOPT - Forward BatchOpt to mibBatchController via SyncBatch.

Syntax:

obj.returnBatchOpt()
obj.returnBatchOpt(BatchOptOut)

Input Arguments:

• BatchOptOut (optional) - override struct; defaults to obj.BatchOpt.

updateBatchOptFromGUI(hObject)¶

UPDATEBATCHOPTFROMGUI - Sync obj.BatchOpt from a single widget.

Syntax:

obj.updateBatchOptFromGUI(hObject)

Input Arguments:

• hObject - AppDesigner widget whose Tag matches a BatchOpt field.

updateContextualWidgets()¶

UPDATECONTEXTUALWIDGETS - Enable or disable context-sensitive widgets.

Syntax:

obj.updateContextualWidgets()

Enables Mean / Std only in Manual mode; ReferenceSliceNo only in BasedOnSlice mode; MaskLayer only for Masked area / Background targets; TimeSeriesNormalization only for Time series.

updateWidgets()¶

UPDATEWIDGETS - Refresh all GUI widgets from the current dataset state.

Syntax:

obj.updateWidgets()

Rebuilds the ColChannel dropdown to match the active dataset, then applies the current BatchOpt to all widgets and updates context-sensitive enable states.