Document mr.calcRfCenter with structured help block

matlab/+mr/calcRfCenter.m

@@ -1,21 +1,75 @@
 function [tc, ic, fi]=calcRfCenter(rf)
-%calcRfCenter Calculate the 'center' of the RF pulse
-%   Returns the time point of the effective rotation calculated as the peak
-%   of the RF amplitude for the shaped pulses and the center of the pulse
-%   for the block pulses. Zeropadding in the RF pulse is considered as a
-%   part of the shape. Delay field of the RF object is not taken into
-%   account.
+%calcRfCenter Calculate the effective center time of an RF pulse.
+%
+%   PURPOSE
+%     Returns the time point of the effective rotation of an RF pulse,
+%     used to align echo timing, set off-resonance phase compensation, and
+%     compute TE/TI delays. For shaped pulses this is the peak of the RF
+%     amplitude; for block pulses it is the midpoint of the constant
+%     plateau. Zero-padding in rf.signal is treated as part of the shape.
+%     The rf.delay field is NOT included in the returned time, so callers
+%     that need an absolute time within a block typically compute
+%     rf.delay + mr.calcRfCenter(rf).
+%
+%   SIGNATURES
+%     tc            = mr.calcRfCenter(rf)    % time of center, seconds
+%     [tc, ic]      = mr.calcRfCenter(rf)    % also integer sample index
+%     [tc, ic, fi]  = mr.calcRfCenter(rf)    % also fractional offset
+%
+%     If rf has a .center field (set by the modern RF constructors
+%     mr.makeSincPulse, mr.makeBlockPulse, mr.makeGaussPulse,
+%     mr.makeArbitraryRf, mr.makeSLRpulse, mr.makeAdiabaticPulse), tc is
+%     taken directly from rf.center and ic is the nearest index in rf.t.
+%     Otherwise tc is computed from the amplitude peak of rf.signal.
+%
+%   INPUTS
+%     rf  [required]  struct, RF event struct. Must have fields .t (seconds, time
+%                     axis on the RF raster) and .signal (complex Hz, waveform).
+%                     If field .center (seconds) is present it is used directly;
+%                     otherwise the function detects the peak of abs(rf.signal).
+%                     Typically produced by mr.makeSincPulse, mr.makeBlockPulse,
+%                     mr.makeGaussPulse, mr.makeArbitraryRf, mr.makeSLRpulse,
+%                     or mr.makeAdiabaticPulse.
+%
+%   OUTPUT
+%     tc   double, seconds, time of the RF center relative to the start
+%            of the RF shape (rf.delay not included)
+%     ic   integer, 1-based index into rf.t / rf.signal of the sample
+%            nearest to tc
+%     fi   double, dimensionless, fractional offset in [-0.5, 0.5] from
+%            rf.t(ic) toward the previous (negative) or next (positive)
+%            sample, normalized by the local raster step. 0 when tc lies
+%            exactly on rf.t(ic) (within 1 ns)
+%
+%   NOTES
+%     - When rf.center is absent, the peak detector treats samples within
+%       0.001% of max(abs(rf.signal)) as part of the same plateau and
+%       returns the midpoint. This is what makes block pulses (constant
+%       amplitude) yield a center at the middle of the pulse rather than
+%       at the first sample.
+%     - rf.delay is intentionally excluded from tc. If a sequence places
+%       an RF event after a delay, the absolute time within the block is
+%       rf.delay + tc.
+%     - Returned tc is on the RF raster (rf.t edges); fi captures the
+%       sub-raster offset when rf.center does not coincide with a sample.
+%
+%   EXAMPLE
+%     sys = mr.opts('MaxGrad', 30, 'GradUnit', 'mT/m', ...
+%                   'MaxSlew', 170, 'SlewUnit', 'T/m/s', ...
+%                   'rfDeadTime', 100e-6);          % bumps rf.delay to 100 us
+%     rf  = mr.makeSincPulse(pi/2, 'Duration', 3e-3, ...
+%                            'SliceThickness', 3e-3, 'system', sys);
+%     % off-resonance phase compensation for an off-center slice:
+%     rf.freqOffset = sys.gamma * 1e-3 * 5e-3;        % 5 mm offset
+%     rf.phaseOffset = -2*pi*rf.freqOffset*mr.calcRfCenter(rf);
+%     % absolute time of the RF center within its block:
+%     tCenter = rf.delay + mr.calcRfCenter(rf);       % 100 us + 1.5 ms = 1.6 ms
+%
+%   SEE ALSO
+%     mr.calcRfBandwidth, mr.calcRfPower, mr.makeSincPulse,
+%     mr.makeBlockPulse, mr.makeGaussPulse, mr.makeArbitraryRf,
+%     mr.makeSLRpulse, mr.makeAdiabaticPulse
 %
-%   Return values:
-%     tc: the time point of the center relative to the beginning of the RF
-%         shape, meaning the edge of the raster cell. This is the main 
-%         return value.
-%     ic: This optional return value contains the corresponding position
-%         in the rf envelope array. This is a value rounded to the next
-%         integer.
-%     fi: Fractional index in the range of -0.5 to 0.5 containing the
-%         fractional position towards the previous or subsequent sample.
-%    
 
 %     % detect zero-padding
 %     last=length(rf.signal);