MATLAB import: Out-of-memory when loading a huge (~850MB) file. May investigate using native functions

[Jerry1144]

As MATLAB moves away from its Java desktop into a new one, its JRE heap size now tops up at 1/4 system memory - 4608MB on my 18GB machine. This is not enough to load my file twice (first in trackmateSpots(), then errors during trackmateFeatureDeclarations()). It feels ironic that a 18GB machine cannot handle something as little as 850 MB.

It seems to be a good time to migrate to matlab.io.xml.* tools. Moreover, there're readstruct('FileType', 'xml') (since R2020b) and readable('FileType', 'xml') (since R2021a) too.

[Jerry1144]

My preliminary testing shows that matlab.io.xml.xpath.Evaluator consumes ridiculous amounts of memory and time (30+GB, lots of swap, 50min) just asking for the /TrackMate[1]/Model node. Direct translation of the script is out of question as of R2025b AppleSilicon.

On the other front, readstruct() and readtable() are both able to finish their work within 2 minutes. I'll share my incarnations of trackmateSpots.m and see what you think of them:

readstruct version: Jerry1144@fa88c6f

readtable version: Jerry1144@77616e3

[tinevez]

Nice!
Yes I had noticed that the XML handling in MATLAB was super slow for reasons unknown to me. I see that you work around it.
Would you care making a PR, so that I can double check on the diff what are the changes you introduce?

[Jerry1144]

Would you care making a PR

It's still a WIP (haven't looked at Edges, Graph, and ImageCalibration), and I want some early feedback as to which path to take. Do you recommend me giving them separate names (trackmateSpotsR20b.m for readstruct(); R21a for readtable()), namespace them (+trackmateReadstruct/trackmateSpots.m), or just replace the original .m files so that a direct diff be made?

so that I can double check on the diff what are the changes you introduce?

I tried to follow your original logic of 1. check first /TrackMate's Model node, 2. load every Spots and distribute into fields 3. look at FeatureDeclarations to fill in variable descriptions. Still, there were some nuances for each of the two.

GitHub probably doesn't like to compare two different named files, so I'll just paste it here. Briefly, readstruct() version: read the /TrackMate/Model node and everything I'll ever need into a structure, but then struct names may have been changed (according to MATLAB identifiers rule) so some additional logic to guess; also does not call out to trackmateFeatureDeclarations.m for parsing. Future plan is to have the separate trackmateFeatureDeclarations.m accept a structure as a secret input, to avoid loading the XML twice.

diff --git a/trackmateSpots.m b/trackmateSpotsR20b.m
index 8a0ae5b..076f50b 100644
--- a/trackmateSpots.m
+++ b/trackmateSpotsR20b.m
@@ -80,141 +80,299 @@
 
 
 % __
-% Jean-Yves Tinevez - 2016 - 2024
+% % Jean-Yves Tinevez & contributors - 2026
 
     %% Import the XPath classes.
-    import javax.xml.xpath.*
-    
+    % import javax.xml.xpath.*
+
+    % readstruct() returns a 4GB struct from a 850 MB xml containing 880k
+    % spots. Memory use sounds reasonable, but there's a lingering ~4GB
+    % footprint even after running `clear('all')`.
+    % This is unlike the readtable() version, whose high watermark is much
+    % higher (owing to multiple passes) but aftermath is clean.
+
+    % matlab.io.xml.xpath displays unacceptable performance even when
+    % requesting a single node (~50 min and 20+GB memory for said file)
+
     %% Constants definition.
 
     TRACKMATE_ELEMENT           = 'TrackMate';
     SPOT_ID_ATTRIBUTE           = 'ID';
     SPOT_NAME_ATTRIBUTE         = 'name';
     ROI_N_POINTS_ATTTRIBUTE     = 'ROI_N_POINTS';
+    ATTRIBUTE_SUFFIX            = '__';
+
+    %% XPath to retrieve the model node
+    xPathExp = ['/', TRACKMATE_ELEMENT, '[1]/Model'];
+    try
+        xmlStruct = readstruct(filePath, 'FileType', 'xml', ...
+            'StructSelector', xPathExp, 'ImportAttributes', true, ...
+            'AttributeSuffix', ATTRIBUTE_SUFFIX);
+    catch ME
+        switch ME.identifier
+            case 'MATLAB:UndefinedFunction'
+                % readstruct() starts from R2020b
+                error('Your MATLAB is too old (pre-R2020b) to run this script.')
+            case 'MATLAB:io:xml:readstruct:NonexistentStructSelector'
+                % <TrackMate>/<Model> not found
+                error('MATLAB:trackMateGraph:BadXMLFile', ...
+                    'File does not seem to be a proper TrackMate file.');
+            otherwise
+                % case 'MATLAB:io:xml:common:InvalidXMLFile', etc.
+                error(ME, 'Failed to read XML file %s.', filePath);
+        end
+    end
+   % redundantFields = {'AllTracks' 'FilteredTracks'};
+   % willRemove = isfield(xmlStruct, redundantFields);
+   % xmlStruct = rmfield(xmlStruct, redundantFields(willRemove));
+
+    %% Extract the spots
+    % Indexing into a field of an array returns a comma-separated list -
+    % concatenate to mimic XPath's behavior. Struct arrays are horizontal.
+    try
+        spotsStruct = [xmlStruct.AllSpots]; % Can be multiple?
+        spotsStruct = [spotsStruct.SpotsInFrame]; % Likely multiple
+        spotsStruct = [spotsStruct.Spot]; % Usually multiple
+
+        % Select the visible spots
+        spotsStruct = spotsStruct([spotsStruct.(['VISIBILITY' ATTRIBUTE_SUFFIX])] == 1);
+    catch ME
+        switch ME.identifier
+            case 'MATLAB:nonExistentField'
+                % XPath points to 0 nodes
+                spotsStruct = struct([SPOT_ID_ATTRIBUTE ATTRIBUTE_SUFFIX], [], ...
+                    [SPOT_NAME_ATTRIBUTE ATTRIBUTE_SUFFIX], []);
+            otherwise
+                rethrow(ME)
+        end
+    end
 
-    %% Open file.
+    nSpots = numel(spotsStruct);
 
+    %% Retrieve spot feature list. Duplication of trackmateFeatureDeclarations.m
+    SPATIAL_UNITS_ATTRIBUTE     = 'spatialunits';
+    TIME_UNITS_ATTRIBUTE        = 'timeunits';
+    FEATURE_KEY_ATTRIBUTE       = 'feature';
+    FEATURE_NAME_ATTRIBUTE      = 'name';
+    FEATURE_SHORTNAME_ATTRIBUTE = 'shortname';
+    FEATURE_DIMENSION_ATTRIBUTE = 'dimension';
+    FEATURE_ISINT_ATTRIBUTE     = 'isint';
+
+    attrs = append({FEATURE_KEY_ATTRIBUTE, FEATURE_NAME_ATTRIBUTE, ...
+        FEATURE_SHORTNAME_ATTRIBUTE FEATURE_DIMENSION_ATTRIBUTE, ...
+        FEATURE_ISINT_ATTRIBUTE}, ...
+        ATTRIBUTE_SUFFIX);
+    fields = cell(size(attrs)+1);
+    fields(1,:) = {'feature' 'name' 'shortName' 'dimension' 'isInt' 'units'};
     try
-        xmlDoc = xmlread(filePath);
-    catch
-        error('Failed to read XML file %s.',filePath);
+        spaceUnits = char(xmlStruct(1).([SPATIAL_UNITS_ATTRIBUTE ATTRIBUTE_SUFFIX]));
+        timeUnits = char(xmlStruct(1).([TIME_UNITS_ATTRIBUTE ATTRIBUTE_SUFFIX]));
+        featureStruct = horzcat(xmlStruct.FeatureDeclarations);
+        featureStruct = horzcat(featureStruct.SpotFeatures);
+        featureStruct = horzcat(featureStruct.Feature);
+        for i = 1 : (numel(attrs)-1)
+            fields{2,i} = cellstr(vertcat(featureStruct.(attrs{i})));
+        end
+        fields{2,i+1} = strcmp('true', vertcat(featureStruct.(attrs{i+1})));
+        fields{2,i+2} = cellfun(@(str)determineUnits(str, spaceUnits, timeUnits), ...
+            fields{2,4}, 'UniformOutput', false);
+        featureMap = containers.Map(fields{2,1}, num2cell(struct(fields{:})));
+    catch ME
+        switch ME.identifier
+            case 'MATLAB:nonExistentField'
+                featureMap = containers.Map('KeyType', 'char', 'ValueType', 'any');
+            otherwise
+                rethrow(ME)
+        end
     end
-    xmlRoot = xmlDoc.getFirstChild();
 
-    if ~strcmp(xmlRoot.getTagName, TRACKMATE_ELEMENT)
-        error('MATLAB:trackMateGraph:BadXMLFile', ...
-            'File does not seem to be a proper TrackMate file.')
+    %% Guess the attribute name from struct names
+    % Valid XML name is a superset of MATLAB variable name, so MATLAB
+    % may have modified them when importing into struct fields
+
+    % Combine knowledge from FeatureDeclarations and user input
+    if exist('featureList', 'var')
+        fList = union( featureList, keys(featureMap));
+    else
+        fList = keys(featureMap);
     end
-    
-    
-    %% XPath to retrieve spot nodes.
-    
-    % Use XPath to retrieve all visible spots.
-    factory = XPathFactory.newInstance;
-    xPath = factory.newXPath;
-    xPathFilter = xPath.compile('//Model/AllSpots/SpotsInFrame/Spot[@VISIBILITY=1]');
-    nodeList = xPathFilter.evaluate(xmlDoc, XPathConstants.NODESET);
-    
-    %% Retrieve spot feature list.
-    
+
+    [fList_mod, havemodd1] = matlab.lang.makeValidName(fList);
+    [fList_mod, havemodd2] = matlab.lang.makeUniqueStrings(fList_mod);
+    fList_mod = append(fList_mod, ATTRIBUTE_SUFFIX);
+    whichModified = havemodd1 | havemodd2;
+
     if nargin < 2 || isempty( featureList )
-        featureList = getSpotFeatureList(nodeList.item(0));
-    end
-    
-    % Remove ID and name, because we will get them anyway.
-    featureList = setdiff( featureList, SPOT_ID_ATTRIBUTE );
-    featureList = setdiff( featureList, SPOT_NAME_ATTRIBUTE );
-    n_features = numel( featureList );
-    
-    %% Get filtered spot IDs.
-
-    % Prepare holders.
-    nSpots      = nodeList.getLength();
-    ID          = NaN( nSpots, 1 );
-    name        = cell( nSpots, 1);
-    features    = NaN( nSpots, n_features );
-    rois        = cell( nSpots, 1);
-
-    % Read all spot nodes.
-    for i = 1 : nSpots
-        node = nodeList.item( i-1 );
-        ID( i )     = str2double( node.getAttribute( SPOT_ID_ATTRIBUTE ) );
-        name{ i }   = char( node.getAttribute( SPOT_NAME_ATTRIBUTE ) );
-        for j = 1 : n_features
-           features( i, j ) = str2double( node.getAttribute( featureList{ j } ) ); 
+        % List of feature is all spot attributes. Look up the original name
+        % if it's *known* to be non-trivially renamed.
+        % Still, we will lose the original attribute name if it doesn't
+        % appear in <FeatureDeclarations>
+
+        featureList_mod = fieldnames(spotsStruct);
+        % May contain a Text field for the node's text
+        featureList_mod = featureList_mod(endsWith(featureList_mod, ATTRIBUTE_SUFFIX));
+        frontOfList = append({SPOT_ID_ATTRIBUTE; SPOT_NAME_ATTRIBUTE}, ATTRIBUTE_SUFFIX);
+        featureList_mod = union(frontOfList, featureList_mod, 'stable');
+        featureList = cell(size(featureList_mod));
+
+        if any(whichModified)
+            renameMap = containers.Map(fList_mod(whichModified), fList(whichModified));
+            willLookup = iskey(renameMap, featureList_mod);
+            for k = 1:numel(featureList_mod)
+                feature_mod = featureList_mod{k};
+                if willLookup(k)
+                    featureList{k} = renameMap(feature_mod);
+                else
+                    featureList{k} = extractBefore(feature_mod, ...
+                        ATTRIBUTE_SUFFIX+textBoundary('end'));
+                end
+            end
+        else
+            featureList = extractBefore(featureList_mod, ...
+                ATTRIBUTE_SUFFIX+textBoundary('end'));
         end
-        
-        % Read ROI coords if it's there.
-        if nargout >= 3
-            coords_str = node.getTextContent();
-            if ~isempty( coords_str )
-                A = sscanf(string(coords_str),'%f');
-                n_points = numel(A) / 2;
-                A = reshape( A, 2, n_points )';
-                rois{i} = A;
+
+    else
+        % List of feature is the input list. Still, the renaming is done
+        % according to real nodes, so we look up the modified names.
+        featureList = featureList(:);
+        if isstring(featureList)
+            featureList = cellstr(featureList);
+        end
+        % Push ID and name to the front
+        frontOfList = {SPOT_ID_ATTRIBUTE; SPOT_NAME_ATTRIBUTE};
+        featureList = union( frontOfList, featureList, 'stable' );
+
+        if any(whiwhModified)
+            renameMapRev = containers.Map(fList(whichModified), fList_mod(whichModified));
+            willLookup = iskey(renameMapRev, featureList);
+            featureList_mod = cell(size(featureList));
+            for k = 1:numel(featureList)
+                feature = featureList{k};
+                if willLookup(k)
+                    featureList_mod{k} = renameMapRev(feature);
+                else
+                    featureList_mod{k} = append(feature, ATTRIBUTE_SUFFIX);
+                end
             end
+        else
+            featureList_mod = append(featureList, ATTRIBUTE_SUFFIX);
         end
     end
-    
-    % Create table.
-    spotTable = table();
-    spotTable.( SPOT_ID_ATTRIBUTE )     = ID;
-    spotTable.( SPOT_NAME_ATTRIBUTE )   = name;
-    for j = 1 : n_features
-       spotTable.( featureList{ j } )   = features( :, j ); 
-    end
-    
-    % Set table metadata.
-    spotTable.Properties.DimensionNames = { 'Spot', 'Feature' };
-    
-    vNames = spotTable.Properties.VariableNames;
-    nVNames = numel( vNames );
-    vDescriptions   = cell( nVNames, 1);
-    vUnits          = cell( nVNames, 1);
-    
-    fs = trackmateFeatureDeclarations( filePath );
-    for k = 1 : nVNames
-        vn = vNames{ k };
-        if strcmp( SPOT_ID_ATTRIBUTE, vn )
-            vDescriptions{ k }  = 'Spot ID';
-            vUnits{ k }         = '';
-        elseif strcmp( SPOT_NAME_ATTRIBUTE, vn )
-            vDescriptions{ k }  = 'Spot name';
-            vUnits{ k }         = '';
-        elseif strcmp( ROI_N_POINTS_ATTTRIBUTE, vn )
-            vDescriptions{ k }  = 'ROI N points';
-            vUnits{ k }         = '';
-        else
-            vDescriptions{ k }  = fs( vn ).name;
-            vUnits{ k }         = fs( vn ).units;
+
+    %% Create table
+    n_features = numel( featureList );
+    spotTable = table('Size', [nSpots n_features], 'VariableNames', featureList, ...
+        'VariableTypes', repmat({'double'}, size(featureList)));
+    for k = 1:n_features
+        featureID = featureList_mod{k};
+        willBeChar = strcmp( [SPOT_NAME_ATTRIBUTE ATTRIBUTE_SUFFIX], featureID );
+
+        if isfield(spotsStruct, featureID)
+            % If *some* values are missing, they are read as missing() and
+            % automatically converted to corresponding missing values upon
+            % concatenation.
+            features = vertcat(spotsStruct.(featureID));
+
+            if willBeChar
+                if ~iscellstr(features) %#ok<ISCLSTR>
+                    if ~isstring(features)
+                        features = string(features);
+                    end
+                    features = cellstr(features);
+                end
+            elseif ~isa(features, 'double')
+                % Is it even possible that other features are accidentally
+                % read as a string? Deal with that anyway
+                features = double(features);
+            end
+
+        else % Asked for a non-existent attribute
+            if willBeChar
+                features = cellstr(strings(nSpots, 1));
+            else
+                features = nan(nSpots, 1 , 'double');
+            end
         end
+
+        spotTable.(featureList{k}) = features;
     end
+
+    %% Set table metadata.
+    spotTable.Properties.DimensionNames = { 'Spot', 'Feature' };
+
+    % vDescriptions   = cell( n_features, 1);
+    % vUnits          = cell( n_features, 1);
+    %
+    % % Secret shortcut - pass the struct to skip reading again.
+    % featureMap = trackmateFeatureDeclarations( xmlStruct );
+
+    [vDescriptions, vUnits] = cellfun(@lookupDescriptionAndUnit, ...
+        featureList, 'UniformOutput', false);
     spotTable.Properties.VariableDescriptions   = vDescriptions;
     spotTable.Properties.VariableUnits          = vUnits;
-    
-    % Generate map ID -> table row number.
-    spotIDMap = containers.Map( ID, 1 : nSpots, ...
+
+    %% Generate map ID -> table row number.
+    spotIDMap = containers.Map( spotTable.ID, 1 : nSpots, ...
         'UniformValues', true);
-    
-    %% Subfunction.
-    
-    function featureList = getSpotFeatureList(node)
-        
-        attribute_map = node.getAttributes;
-        nAttributes = attribute_map.getLength;
-        
-        featureList = cell(nAttributes - 1, 1); % -1 for the spot name, which we do not take
-        index = 1;
-        for ii = 1 : nAttributes
-            
-            namel = node.getAttributes.item(ii-1).getName;
-            if strcmp(namel, SPOT_NAME_ATTRIBUTE)
-                continue;
+
+    %% Read ROI coords if it's requested.
+    if nargout >= 3
+        rois = cell(nSpots, 1);
+        if isfield(spotsStruct, 'Text')
+            for i = 1 : nSpots
+                coords_str = spotsStruct(i).Text;
+                if ~isempty( coords_str )
+                    A = sscanf(coords_str,'%f');
+                    A = reshape(A, 2, []).';
+                    rois{i} = A;
+                end
             end
-            featureList{index} = char(namel);
-            index = index + 1;
-            
         end
     end
-    
-end
\ No newline at end of file
+
+    %% Subfunction.
+    function [description, unit] = lookupDescriptionAndUnit(featureName)
+        switch featureName
+            case SPOT_ID_ATTRIBUTE
+                description = 'Spot ID';
+                unit        = '';
+            case SPOT_NAME_ATTRIBUTE
+                description = 'Spot ID';
+                unit        = '';
+            case ROI_N_POINTS_ATTTRIBUTE
+                description = 'ROI N points';
+                unit        = '';
+            otherwise
+                description = featureMap( featureName ).name;
+                unit        = featureMap( featureName ).units;
+        end
+    end
+end
+
+function  units = determineUnits( dimension, spaceUnits, timeUnits )
+    switch ( dimension )
+        case 'ANGLE'
+            units = 'Radians';
+        case 'INTENSITY'
+            units = 'Counts';
+        case 'INTENSITY_SQUARED'
+            units = 'Counts^2';
+        case' NONE'
+            units = '';
+        case { 'POSITION', 'LENGTH' }
+            units = spaceUnits;
+        case 'QUALITY'
+            units = 'Quality';
+        case 'TIME'
+            units = timeUnits;
+        case 'VELOCITY'
+            units = [ spaceUnits '/' timeUnits];
+        case 'RATE'
+            units = [ '/' timeUnits];
+        case 'STRING'
+            units = '';
+        otherwise
+            units = 'no unit';
+    end
+end

readtable() version: To read through the file as few time as possible, call trackmateFeatureDeclarations.m for the initial validity check, and directly construct XMLImportOptions instead of calling detectImportOptions() where possible. There's a commented-out section of "reading the first Spot node for attributes" as that requires detectImportOptions(), and it's replaced by consulting

diff --git a/trackmateSpots.m b/trackmateSpotsR21a.m
index 8a0ae5b..51b66d0 100644
--- a/trackmateSpots.m
+++ b/trackmateSpotsR21a.m
@@ -80,141 +80,165 @@
 
 
 % __
-% Jean-Yves Tinevez - 2016 - 2024
+% Jean-Yves Tinevez & contributors - 2026
 
-    %% Import the XPath classes.
-    import javax.xml.xpath.*
-    
     %% Constants definition.
 
-    TRACKMATE_ELEMENT           = 'TrackMate';
+    % TRACKMATE_ELEMENT           = 'TrackMate';
     SPOT_ID_ATTRIBUTE           = 'ID';
     SPOT_NAME_ATTRIBUTE         = 'name';
     ROI_N_POINTS_ATTTRIBUTE     = 'ROI_N_POINTS';
 
     %% Open file.
+    % This alone takes as much time as calling
+    % trackmateFeatureDeclarations(filePath) (which has 4x readtable())!
 
-    try
-        xmlDoc = xmlread(filePath);
-    catch
-        error('Failed to read XML file %s.',filePath);
-    end
-    xmlRoot = xmlDoc.getFirstChild();
+        % xmlDoc = parseFile(matlab.io.xml.dom.Parser, filePath)
+        % xmlNode = xmlDoc.getFirstChildNode;
 
-    if ~strcmp(xmlRoot.getTagName, TRACKMATE_ELEMENT)
-        error('MATLAB:trackMateGraph:BadXMLFile', ...
-            'File does not seem to be a proper TrackMate file.')
-    end
-    
-    
     %% XPath to retrieve spot nodes.
-    
     % Use XPath to retrieve all visible spots.
-    factory = XPathFactory.newInstance;
-    xPath = factory.newXPath;
-    xPathFilter = xPath.compile('//Model/AllSpots/SpotsInFrame/Spot[@VISIBILITY=1]');
-    nodeList = xPathFilter.evaluate(xmlDoc, XPathConstants.NODESET);
-    
+    % Note evaluate() is called on a different object than JavaX's.
+    % This takes ~50min to read through an 850 MB file (R25b). Unacceptable
+
+        % evalObj = matlab.io.xml.xpath.Evaluator();
+        % filterObj = evalObj.compileExpression('//Model/AllSpots/SpotsInFrame/Spot[@VISIBILITY=1]');
+        % nodeList = evalObj.evaluate(filterObj,xmlDoc, EvalResultType.NodeSet);
+
     %% Retrieve spot feature list.
-    
+
+    % We'll call trackmateFeatureDeclarations() to fill in table properties
+    % no matter what, so let's reuse that one's validation function.
+    try
+        fs = trackmateFeatureDeclarationsR21a( filePath );
+    catch ME
+        throw(ME)
+    end
+
+    % Difference from original code: for performance reasons, featureList
+    % is taken from <FeatureDelarations> instead of the first <Spot> node
     if nargin < 2 || isempty( featureList )
-        featureList = getSpotFeatureList(nodeList.item(0));
+        featureList = keys(fs);
     end
-    
-    % Remove ID and name, because we will get them anyway.
-    featureList = setdiff( featureList, SPOT_ID_ATTRIBUTE );
-    featureList = setdiff( featureList, SPOT_NAME_ATTRIBUTE );
-    n_features = numel( featureList );
-    
-    %% Get filtered spot IDs.
-
-    % Prepare holders.
-    nSpots      = nodeList.getLength();
-    ID          = NaN( nSpots, 1 );
-    name        = cell( nSpots, 1);
-    features    = NaN( nSpots, n_features );
-    rois        = cell( nSpots, 1);
-
-    % Read all spot nodes.
-    for i = 1 : nSpots
-        node = nodeList.item( i-1 );
-        ID( i )     = str2double( node.getAttribute( SPOT_ID_ATTRIBUTE ) );
-        name{ i }   = char( node.getAttribute( SPOT_NAME_ATTRIBUTE ) );
-        for j = 1 : n_features
-           features( i, j ) = str2double( node.getAttribute( featureList{ j } ) ); 
-        end
-        
-        % Read ROI coords if it's there.
-        if nargout >= 3
-            coords_str = node.getTextContent();
+
+    % % Take featureList from the first <Spot> node
+    % if nargin < 2 || isempty( featureList )
+    %     ATTRIBUTE_SUFFIX = '__';
+    %     try
+    %         opt = detectImportOptions(filePath, 'FileType', 'xml', ...
+    %             'RowSelector', '/TrackMate/Model/AllSpots/SpotsInFrame/Spot[1]', ...
+    %             'ImportAttributes', true, 'AttributeSuffix', ATTRIBUTE_SUFFIX, ...
+    %             'VariableNamingRule', 'preserve');
+    %         featureList = opt.SelectedVariableNames;
+    %         featureListSel = endsWith(featureList, ATTRIBUTE_SUFFIX);
+    %         featureList = extractBefore(featureList(featureListSel), ...
+    %             ATTRIBUTE_SUFFIX+textBoundary('end'));
+    %         if isstring(featureList)
+    %             featureList = cellstr(featureList);
+    %         end
+    %     catch ME
+    %         switch ME.identifier
+    %             case 'MATLAB:io:xml:detection:RowSelectorInvalidSelection'
+    %                 % No spots in file
+    %                 featureList = {};
+    %             otherwise
+    %                 throw(ME)
+    %         end
+    %     end
+    % end
+    %% Create table.
+    opt = makeXMLOptionsSpot(featureList);
+
+    % Read ROI coords if it's requested
+    if nargout >= 3
+        willReadROIs = true;
+        opt.SelectedVariableNames = [cellstr(opt.SelectedVariableNames) {'rois'}];
+    else
+        willReadROIs = false;
+    end
+
+    spotTable = readtable(filePath, opt);
+    nSpots = height(spotTable);
+
+    if willReadROIs
+        roistrs = spotTable.rois;
+        rois = cell( nSpots, 1 );
+        for i = 1 : nSpots
+            coords_str = roistrs{i};
             if ~isempty( coords_str )
-                A = sscanf(string(coords_str),'%f');
-                n_points = numel(A) / 2;
-                A = reshape( A, 2, n_points )';
+                A = sscanf( coords_str, '%f' );
+                A = reshape( A, 2, [] ).';
                 rois{i} = A;
             end
         end
+        spotTable = removevars(spotTable, 'rois');
     end
-    
-    % Create table.
-    spotTable = table();
-    spotTable.( SPOT_ID_ATTRIBUTE )     = ID;
-    spotTable.( SPOT_NAME_ATTRIBUTE )   = name;
-    for j = 1 : n_features
-       spotTable.( featureList{ j } )   = features( :, j ); 
-    end
-    
+
     % Set table metadata.
     spotTable.Properties.DimensionNames = { 'Spot', 'Feature' };
-    
-    vNames = spotTable.Properties.VariableNames;
-    nVNames = numel( vNames );
-    vDescriptions   = cell( nVNames, 1);
-    vUnits          = cell( nVNames, 1);
-    
-    fs = trackmateFeatureDeclarations( filePath );
-    for k = 1 : nVNames
-        vn = vNames{ k };
-        if strcmp( SPOT_ID_ATTRIBUTE, vn )
-            vDescriptions{ k }  = 'Spot ID';
-            vUnits{ k }         = '';
-        elseif strcmp( SPOT_NAME_ATTRIBUTE, vn )
-            vDescriptions{ k }  = 'Spot name';
-            vUnits{ k }         = '';
-        elseif strcmp( ROI_N_POINTS_ATTTRIBUTE, vn )
-            vDescriptions{ k }  = 'ROI N points';
-            vUnits{ k }         = '';
-        else
-            vDescriptions{ k }  = fs( vn ).name;
-            vUnits{ k }         = fs( vn ).units;
-        end
-    end
+
+    [vDescriptions,vUnits] = cellfun(@determineDescriptions, ...
+        cellstr(spotTable.Properties.VariableNames), ...
+        "UniformOutput",false);
+
     spotTable.Properties.VariableDescriptions   = vDescriptions;
     spotTable.Properties.VariableUnits          = vUnits;
-    
-    % Generate map ID -> table row number.
-    spotIDMap = containers.Map( ID, 1 : nSpots, ...
-        'UniformValues', true);
-    
+
+    %% Generate map ID -> table row number.
+    if nargout >= 2
+        spotIDMap = containers.Map( spotTable.ID, 1 : nSpots, ...
+            'UniformValues', true);
+    end
+
     %% Subfunction.
-    
-    function featureList = getSpotFeatureList(node)
-        
-        attribute_map = node.getAttributes;
-        nAttributes = attribute_map.getLength;
-        
-        featureList = cell(nAttributes - 1, 1); % -1 for the spot name, which we do not take
-        index = 1;
-        for ii = 1 : nAttributes
-            
-            namel = node.getAttributes.item(ii-1).getName;
-            if strcmp(namel, SPOT_NAME_ATTRIBUTE)
-                continue;
-            end
-            featureList{index} = char(namel);
-            index = index + 1;
-            
+
+    function opt = makeXMLOptionsSpot(featureList)
+        % Remove ID and name, because we will get them anyway.
+        featureList = setdiff( featureList, SPOT_ID_ATTRIBUTE );
+        featureList = setdiff( featureList, SPOT_NAME_ATTRIBUTE );
+
+        nodePath = '/TrackMate/Model/AllSpots/SpotsInFrame/Spot[@VISIBILITY=1]';
+
+        n_features = numel( featureList );
+        varNames = cell( n_features + 3, 1 ); % { ID; name; featureList; rois }
+        varTypes = repmat( {'double'}, n_features + 3, 1 );
+        varNames{1} = SPOT_ID_ATTRIBUTE;
+        % ID is imported as double, mimicking the original code
+        varNames{2} = SPOT_NAME_ATTRIBUTE;
+        varTypes{2} = 'char';
+        varNames(3:end-1) = featureList;
+        varNames{end} = 'rois';
+        varTypes{end} = 'char';
+        % The VISIBILITY attribute wasn't given special treatment (ignore,
+        % or read as logical), just like the original code
+
+        varSelectors = append( '(', nodePath, ')/@', varNames );
+        varSelectors{end} = nodePath; % Select the node itself for its text
+
+        opt = xmlImportOptions( 'NumVariables', n_features+3, ...
+            'VariableNames', varNames, 'VariableTypes', varTypes, ...
+            'VariableSelectors', varSelectors, 'RowSelector', nodePath, ...
+            'SelectedVariableNames', 1:n_features+2, ...
+            'VariableNamingRule', 'preserve', 'MissingRule', 'fill' );
+
+        % Preserve whitespaces in name and rois
+        opt = setvaropts(opt, [2 n_features+3], 'WhitespaceRule', 'preserve');
+    end
+
+    function  [desc, unit] = determineDescriptions( varName )
+        switch ( varName )
+            case SPOT_ID_ATTRIBUTE
+                desc = 'Spot ID';
+                unit = '';
+            case SPOT_NAME_ATTRIBUTE
+                desc = 'Spot name';
+                unit = '';
+            case ROI_N_POINTS_ATTTRIBUTE
+                desc = 'ROI N points';
+                unit = '';
+            otherwise
+                desc = fs(varName).name;
+                unit = fs(varName).units;
         end
     end
-    
-end
\ No newline at end of file
+end
diff --git a/trackmateFeatureDeclarations.m b/trackmateFeatureDeclarationsR21a.m
index b066b54..c182fb5 100644
--- a/trackmateFeatureDeclarations.m
+++ b/trackmateFeatureDeclarationsR21a.m
@@ -39,13 +39,14 @@
 %         units: 'pixels'
 
 % __
-% Jean-Yves Tinevez - 2016
+% Jean-Yves Tinevez & contributors - 2026
 
 
     %% Import the XPath classes.
-    import javax.xml.xpath.*
-    
-    
+    % import javax.xml.xpath.*
+    % import matlab.io.xml.dom.*
+    % import matlab.io.xml.xpath.*
+
     %% Constants definition.
     TRACKMATE_ELEMENT           = 'TrackMate';
     SPATIAL_UNITS_ATTRIBUTE     = 'spatialunits';
@@ -55,89 +56,85 @@
     FEATURE_SHORTNAME_ATTRIBUTE = 'shortname';
     FEATURE_DIMENSION_ATTRIBUTE = 'dimension';
     FEATURE_ISINT_ATTRIBUTE     = 'isint';
-        
-    
-    %% Open and check XML.
-    
+
+
+    %% Open and check XML...
+    % detectImportOptions(filename) would return an XMLImportOptions, but
+    % takes (a lot of) time to scan through the file. Instead, we construct
+    % the option directly, and let readtable() throw.
+    varNames = {SPATIAL_UNITS_ATTRIBUTE TIME_UNITS_ATTRIBUTE};
+    modelPath = ['/' TRACKMATE_ELEMENT '[1]/Model'];
     try
-        xmlDoc = xmlread(filePath);
-    catch
-        error('Failed to read XML file %s.',filePath);
+        opt_unit = xmlImportOptions('NumVariables', 2, ...
+            'VariableNames', varNames, 'VariableTypes', {'char' 'char'}, ...
+            'VariableNamingRule', 'preserve', 'RowSelector', modelPath, ...
+            'VariableSelectors', append('(', modelPath, ')/@', varNames));
+        unitTbl = readtable(filePath, opt_unit);
+    catch ME
+        switch ME.identifier
+            case 'MATLAB:UndefinedFunction'
+                % xmlImportOptions() Starts from R2021a
+                error('Your MATLAB is too old (pre-R2021a) to run this script.');
+            otherwise
+                % Attach the error struct to facilitate diagnostics.
+                error(ME, 'Failed to read XML file %s.', filePath);
+        end
     end
-    xmlRoot = xmlDoc.getFirstChild();
-    
-    if ~strcmp(xmlRoot.getTagName, TRACKMATE_ELEMENT)
+
+    if height(unitTbl) < 1
+        % No attribute read from the model node
         error('MATLAB:trackMateGraph:BadXMLFile', ...
-            'File does not seem to be a proper TrackMate file.')
+            'File does not seem to be a proper TrackMate file.');
     end
-    
-    factory = XPathFactory.newInstance;
-    xpath = factory.newXPath;
-    
-    %% Retrieve physical units.
-    
-    modelPath   =  xpath.compile('/TrackMate/Model');
-    modelNode   = modelPath.evaluate(xmlRoot, XPathConstants.NODESET).item(0);
-    spaceUnits  = char( modelNode.getAttribute( SPATIAL_UNITS_ATTRIBUTE ) );
-    timeUnits   = char( modelNode.getAttribute( TIME_UNITS_ATTRIBUTE ) );
-    
+
+    %% And retrieve physical units.
+    spaceUnits = unitTbl{1,SPATIAL_UNITS_ATTRIBUTE}{1};
+    timeUnits = unitTbl{1,TIME_UNITS_ATTRIBUTE}{1};
+
     %% XPath to retrieve spot feature declarations.
-    
-    spotFeatureFilter = xpath.compile('/TrackMate/Model/FeatureDeclarations/SpotFeatures/Feature');
-    spotFeatureNodes = spotFeatureFilter.evaluate(xmlDoc, XPathConstants.NODESET);
-    nSpotFeatureNodes = spotFeatureNodes.getLength();
-    
-    sf = containers.Map();
-    for i = 1 : nSpotFeatureNodes
-        f = readFeature( spotFeatureNodes.item( i-1 ), spaceUnits, timeUnits );
-        sf( f.key ) = f;
-    end
-    
+    % /TrackMate[1]/Model/FeatureDeclarations/EdgeFeatures/Feature
+    opt_spot = makeXMLOptionsFeature('SpotFeatures');
+    sf = transformFeatureTable(readtable(filePath, opt_spot), spaceUnits, timeUnits);
+
     %% XPath to retrieve edge feature declarations.
-    
-    edgeFeatureFilter = xpath.compile('/TrackMate/Model/FeatureDeclarations/EdgeFeatures/Feature');
-    edgeFeatureNodes = edgeFeatureFilter.evaluate(xmlDoc, XPathConstants.NODESET);
-    nEdgeFeatureNodes = edgeFeatureNodes.getLength();
-    
-    ef = containers.Map();
-    for i = 1 : nEdgeFeatureNodes
-        f = readFeature( edgeFeatureNodes.item( i-1 ), spaceUnits, timeUnits );
-        ef( f.key ) = f;
+    if nargout >= 2
+        % /TrackMate[1]/Model/FeatureDeclarations/EdgeFeatures/Feature
+        opt_edge = makeXMLOptionsFeature('EdgeFeatures');
+        ef = transformFeatureTable(readtable(filePath, opt_edge), spaceUnits, timeUnits);
     end
-    
+
     %% XPath to retrieve track feature declarations.
-    
-    trackFeatureFilter = xpath.compile('/TrackMate/Model/FeatureDeclarations/TrackFeatures/Feature');
-    trackFeatureNodes = trackFeatureFilter.evaluate(xmlDoc, XPathConstants.NODESET);
-    nTrackFeatureNodes = trackFeatureNodes.getLength();
-    
-    tf = containers.Map();
-    for i = 1 : nTrackFeatureNodes
-        f = readFeature( trackFeatureNodes.item( i-1 ), spaceUnits, timeUnits );
-        tf( f.key ) = f;
+    if nargout >= 3
+        % /TrackMate[1]/Model/FeatureDeclarations/TrackFeatures/Feature
+        opt_track = makeXMLOptionsFeature('TrackFeatures');
+        tf = transformFeatureTable(readtable(filePath, opt_track), spaceUnits, timeUnits);
     end
-    
-    
-    
     %% Subfunctions.
-    
-    function f = readFeature(featureNode, spaceUnits, timeUnits)
-       
-        key         = char( featureNode.getAttribute( FEATURE_KEY_ATTRIBUTE ) );
-        name        = char( featureNode.getAttribute( FEATURE_NAME_ATTRIBUTE ) );
-        shortName   = char( featureNode.getAttribute( FEATURE_SHORTNAME_ATTRIBUTE ) );
-        dimension   = char( featureNode.getAttribute( FEATURE_DIMENSION_ATTRIBUTE ) );
-        isInt       = strcmp( 'true', char( featureNode.getAttribute( FEATURE_ISINT_ATTRIBUTE ) ) );
-        units       = determineUnits( dimension, spaceUnits, timeUnits );
-        
-        f = struct();
-        f.key       = key;
-        f.name      = name;
-        f.shortName = shortName;
-        f.dimension = dimension;
-        f.isInt     = isInt;
-        f.units     = units;
-        
+
+    % It's predetermined that 5 attributes exist at a fixed xpath. Let's
+    % fill an XMLImportOptions directly. Also control the names and orders
+    % of variables here.
+    function opt = makeXMLOptionsFeature(nodeName)
+        nodePath = ['/'  TRACKMATE_ELEMENT  '[1]/Model/FeatureDeclarations/' nodeName '/Feature'];
+        nodeSelectors = append('(', nodePath, ')/@', {FEATURE_KEY_ATTRIBUTE ...
+        FEATURE_NAME_ATTRIBUTE FEATURE_SHORTNAME_ATTRIBUTE ...
+        FEATURE_DIMENSION_ATTRIBUTE FEATURE_ISINT_ATTRIBUTE});
+
+        opt = xmlImportOptions('NumVariables', 5, ...
+            'VariableNames', {'key' 'name' 'shortName' 'dimension' 'isInt'}, ...
+            'VariableTypes', {'char' 'char' 'char' 'char' 'logical'}, ...
+            'RowSelector', nodePath, 'VariableSelectors', nodeSelectors);
+    end
+end
+
+    % Fill in the Units, and transform into Map
+    function featureMap = transformFeatureTable(featureTable, spaceUnits, timeUnits)
+        units = cellfun(@(dim)determineUnits(dim, spaceUnits, timeUnits), ...
+            featureTable.dimension, 'UniformOutput', false);
+        featureTable = addvars(featureTable, units, 'NewVariableNames', 'units');
+
+        featureStruct = table2struct(featureTable);
+        featureMap = containers.Map({featureStruct.key}.', num2cell(featureStruct));
     end
 
     function  units = determineUnits( dimension, spaceUnits, timeUnits )
@@ -166,4 +163,4 @@
                 units = 'no unit';
         end
     end
-end
\ No newline at end of file
+

[tinevez]

The PR is really helpful for me to test and benchmark everything. I will review the changes and the code with a PR.

[Jerry1144]

@tinevez I've prepared a final version, mimicking your code style and naming.

Still, if it's >R2021a, it might make sense to introduce new styles: Name=Value, arguments block, strings for text handling, etc. I'm curious how much improvement those can bring.