Define table specifications V1

[tcompa]

• Add a version to the attributes of all ROI-table Zarr groups. Maybe something like "fractal_roi_table_version": "1"? Note that for the moment we are not planning to do anything with it, but in this way the newly-created Zarrs will include this information.
• Add a ROI-v1 docs page, with a description of the current status
• Include a brief list of ongoing discussions or aspects that will likely change in the future. These could include both shorter-term perspectives (e.g. not hard-coding micrometer in column names) and longer-term ones (e.g. re-evaluate the choice of AnnData).

[tcompa]

Given the shape that #582 is taking, I wonder whether we should be more granular in the definition of versions.
That is, should the zarr attributes of a table group be as follows?

// table with no additional specifications
{
 "fractal_table_version": "1",
}
// basic ROI table  (naming is WIP)
{
 "fractal_table_version": "1",
 "type": "basic_roi_table",
}
// advanced ROI table (naming is WIP)
{
 "fractal_table_version": "1",
 "type": "advanced_roi_table",
}
// feature table
{
 "fractal_table_version": "1",
 "type": "feature_table",
}

The benefit here is that based on a zarr attribute we immediately know whether some operations on the table make sense.

For instance we already use the type="ngff:region_table" information in a few places:

• Masked loading only works for this type of tables, which is checked via the is_ROI_table_valid(table_path, use_masks=True
• Also _preprocess_input checks that type is "ngff:region_table"
• When writing a table which has that type, we also check that attributes comply with the specs. For the moment it's a soft check (ref Review use of write_table in registration tasks #594), but we could make it a strict check if we want to only write spec-compliant tables. Note that we'd still be able to write arbitrary tables, but then we would not include any type attribute (while still including fractal_table_version="1").

NOTE: if we start using our own table types (e.g. basic_roi_table, advanced_roi_table, feature_table -- all TBD), then we need to also support the legacy type ngff:region_table, to support tables of existing OME-Zarrs. My current understanding is that we used ngff:region_table simply as a placeholder for what would then become advanced_roi_table, and then we could easily maintain backwards compatibility by treating the two types as synonyms.

[tcompa]

Note: the proposal in the previous comment concerns the specs definition, but it's still acceptable to postpone a bit the actual implementation of spec-compliant tables.
That is, we can now define (as part of #582) the V1 specs, and then refactor the internal tools and helper functions in the appropriate way in upcoming releases.

---

For instance we may start to encode part of the specs in the code, e.g. the required columns for a ROI tables could be stored in an upcoming lib_tables.py module.

And we could also take the opportunity to clean up the structure of the helper functions, to keep the ones referred to different parts of the specs separated. We can decide how far to push the modularity, but just to have a random example we could go as far as:

fractal_tasks_core
    tables
        v1
            lib_tables.py (which includes, e.g.
            lib_roi_tables.py
            lib_feature_tables.py
            lib_write_table.py

(or any other arrangement of the same kind of information.. e.g. the v1/v2 do not need to be specific subfolders)