get_ljsctc.m

% wrapper to generate leverjs CTC parameter structure
%   really missing python's named params here...
% arc jan 22

% HELLO! LJSCTC -- START HERE
%   this file defines a param struct with all the file system info needed
%   to import a ctc movie to leverjs format, process that movie and then
%   export it back to ctc output format. it's specific to the ctc file
%   naming and formats and how the scoring is done.
%
% rawImagePath -- ctc tiff folder. this is the full path to the /01 or /02 folder with the
%   raw image tiffs
%
% outPath -- working folder for .LEVER file anc ctc formatted output
%
% expName -- unique name for dataset, either BF-C2DL-HSC_training_01 or 
%   BF-C2DL-HSC_challenge_01 for dataset BF-C2DL-HSC/01
%
% pixelPhysicalSize -- microscope metadata. important to get right, for
%       both visualization and segmentation. e.g. [0.5,0.5,1] for (x,y,z) 
%       pixel dimensions. If empty ([]), ignored. Same units as the
%       minimumRadius_um in the segParams field.
%
% segParams -- see getSegParams() in this folder for suggestions. For best
%   results, use getSegParams and base this off of an existing dataset. If
%   this is empty ([]), then we will attempt to learn the best params
%
% if segParams is not empty, the following parameters are ignored
%   gtConfig - one of : 'GT','ST','GT+ST','allGT','allST,'allGT+allST'
%       we use expName and gtConfig to extract a previously trained
%       parameter set
%   gtTrainingPath : wildcard path specifying set of man_seg tiffs to process
%       e.g. '/path/to/myDataset/**/man_seg*.tif'. A dir(gtTrainingPath)
%       should produce a list of tif segmentation result images.
%   
% gtEvalPath - if specified, use this as path to the ground truth folder
%   (e.g. /g/ctc2021/2d_BF-C2DL-HSC_training/BF-C2DL-HSC/01_GT). This is
%   only used to score the dataset after running it. If not needed, set to
%   empty ([]). NOTE if you set gtEvalPath, the ctc scoring algorithms will
%   be run BUT the outputs will not be put in the -CONFIG subfolder as the
%   ctc scoring algorithms do not accept that option. Instead outputs will
%   be written to 0?_RES
%
% gtConstraintPath - path to GT for limiting cells tracked, e.g. for large
%   datasets (DRO, TRIF, etc.)
% e.g.
% expName='2d_DIC-C2DH-HeLa_training_01';ljsctc=get_ljsctc(expName)
function ljsctc=get_ljsctc(expName,outPath)

ljsctc = [];
if ~exist('outPath','var')
    outPath = './output';
end
ljsctc.outPath = outPath;
ljsctc.expName=expName;
[baseName,movieID,trainOrChallenge]=LJSCTC.nameParts(expName);
% to omit a field, set it to []. rawImagePath,outPath,segParams expName, are minimum
% required param set
ljsctc.rawImagePath = ['/g/gRaw/ctc2021/' expName(1:end-3) '/' baseName(4:end) '/' movieID];
% THIS IS IMPORTANT! leverjs uses physical-based measurements. you must set
% the correct pixel (voxel) physical size...(always a 3 vector). NOTE that
% some of the pixel physical sizes are encoded in the supplied tiff
% metadata incorrectly! so, the ones we use are set manually from the ctc
% website
ljsctc.strDB=fullfile(ljsctc.outPath,[expName '.LEVER']);
% the preferred way to get segparams. if you set segParams, we use that
datasetSpecifier=baseName(4:end);
[sp,pixelSize]=getSegParams(datasetSpecifier); % from the manual tuned cache
if ~isempty(sp)
    if length(sp.minimumRadius_um)==3
        sp.minimumRadius_um = [0.5,1,0.5].*sp.minimumRadius_um;
    else
        sp.minimumRadius_um=0.5*sp.minimumRadius_um;
    end
    ljsctc.segParams = sp;    
    ljsctc.pixelPhysicalSize=pixelSize;
else
    % is you don't have an sp here, we'll try to learn it for you...if you
    % get stuck reach out to andy here...this code path will generally work
    % well...
end
% which ground truth to use, and where to write exported output
ljsctc.gtConfig='GT';
% if no ljsctc.segparams, and no match in the cached settings list, train a new
% classifier to predict segParams. we'll use all the tiffs returned by this
% next path string. try e.g. dir(ljsctc.gtTrainingPath) to verify it's the
% man_seg tiffs
gtRoot=[ljsctc.rawImagePath(1:strfind(ljsctc.rawImagePath,baseName)+length(baseName))];
gtTraining=[gtRoot 'training/**/man_seg*.tif'];
ljsctc.gtTrainingPath=gtTraining;
% verify training path with next line...
% fprintf(1,'ljsctc found %d training images\n',length(dir(ljsctc.gtTrainingPath)));
if strcmp(trainOrChallenge,'training')
    % this is passed to CTC scoring code
    ljsctc.gtEvalPath = [gtRoot 'training/' datasetSpecifier '/' movieID '_GT'];
else
    % this is passed to CTC scoring code
    ljsctc.gtEvalPath = [];
end

% used for e.g. TRIF,TRIC,DRO datasets where we don't export full movie
% (we still process whole thing though)
ljsctc.gtConstraintPath = [];