Changeset 3351


Ignore:
Timestamp:
11/09/07 11:29:24 (12 years ago)
Author:
curtis
Message:

Flesh out the metadata guide a bit more.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/loci/formats/doc/metadata-guide.txt

    r3118 r3351  
    1717Each of these three facilities will be discussed in its own section. 
    1818 
    19                                  Core Metadata 
    20                                 --------------- 
     19                               I. Core Metadata 
     20                              ------------------ 
    2121 
    2222For a series of images to form a coherent dataset, certain parameters are 
     
    2727following. The first column lists methods of the IFormatReader interface 
    2828relevant to obtaining core metadata values. The second column lists the 
    29 corresponding field of the CoreMetadata class. 
     29corresponding field of the CoreMetadata class, which encapsulates all of the 
     30core metadata parameters within a single object. 
    3031 
    3132      IFormatReader method | CoreMetadata parameter  
    3233     ----------------------+------------------------ 
    3334         getCoreMetadata() | (all) 
    34           getSeriesCount() | - 
     35          getSeriesCount() | imageCount.length (e.g.) 
    3536           getImageCount() | imageCount 
    3637                getSizeX() | sizeX 
     
    5455             getMetadata() | seriesMetadata 
    5556 
    56 CoreMetadata getCoreMetadata() : 
    57   TODO. 
    58  
    59 int getSeriesCount() : 
    60   TODO. setSeries(int), getSeries(). 
    61  
    62 int getImageCount() : 
    63   TODO. 
    64  
    65 int getSizeX() : 
    66   TODO. 
    67  
    68 int getSizeY() : 
    69   TODO. 
    70  
    71 int getSizeZ() : 
    72   TODO. 
    73  
    74 int getSizeC() : 
    75   TODO. 
    76  
    77 int getSizeT() : 
    78   TODO. 
    79  
    80 int getEffectiveSizeC() : 
    81   TODO. 
    82  
    83 int getRGBChannelCount() : 
    84   TODO. 
    85  
    86 boolean isRGB() : 
    87   TODO. 
    88  
    89 int getThumbSizeX() : 
    90   TODO. 
    91  
    92 int getThumbSizeY() : 
    93   TODO. 
    94  
    95 int getPixelType() : 
    96   TODO. 
    97  
    98 int[] getChannelDimLengths() : 
    99   TODO. 
    100  
    101 String[] getChannelDimTypes() : 
    102   TODO. 
    103  
    104 String getDimensionOrder() : 
    105   TODO. 
    106  
    107 boolean isOrderCertain() : 
    108   TODO. 
    109  
    110 boolean isLittleEndian() : 
    111   TODO. 
    112  
    113 boolean isInterleaved() : 
    114   TODO. 
    115  
    116 boolean isInterleaved(int) : 
    117   TODO. 
    118  
    119 Hashtable getMetadata() : 
    120   TODO. 
    121  
    122 Metadata classes: 
    123   CoreMetadata 
    124  
    125                                Original Metadata 
    126                               ------------------- 
    127  
    128 void setMetadataCollected(boolean) : 
    129   TODO. 
    130  
    131 boolean isMetadataCollected() : 
    132   TODO. 
    133  
    134 Object getMetadataValue(String) : 
    135   TODO. 
    136  
    137 Hashtable getMetadata() : 
    138   TODO. 
    139  
    140 void setMetadataFiltered(boolean) : 
    141   TODO. 
    142  
    143 boolean isMetadataFiltered() : 
    144   TODO. 
    145  
    146                           Standardization to OME-XML 
    147                          ---------------------------- 
    148  
    149 IFormatReader: 
    150  
    151 void setOriginalMetadataPopulated(boolean) : 
    152   TODO. 
    153  
    154 boolean isOriginalMetadataPopulated() : 
    155   TODO. 
    156  
    157 void isMetadataComplete() : 
    158   TODO. 
    159  
    160 void setMetadataStore(MetadataStore) : 
    161   TODO. 
    162  
    163 void getMetadataStore() : 
    164   TODO. 
    165  
    166 void getMetadataStoreRoot() : 
    167   TODO. 
    168  
    169 IFormatWriter: 
    170  
    171 void setMetadataRetrieve(MetadataRetrieve) : 
    172   TODO. 
    173  
    174 MetadataRetrieve getMetadataRetrieve() : 
    175   TODO. 
    176  
    177 Metadata classes: 
    178   MetadataStore 
    179   MetadataRetrieve 
    180   OMEXMLMetadata 
    181   DummyMetadata 
    182   AggregateMetadataStore 
    183   MetadataTools 
     57  CoreMetadata getCoreMetadata() : 
     58    TODO. 
     59 
     60  int getSeriesCount() : 
     61    TODO. setSeries(int), getSeries(). 
     62 
     63  int getImageCount() : 
     64    TODO. 
     65 
     66  int getSizeX() : 
     67    TODO. 
     68 
     69  int getSizeY() : 
     70    TODO. 
     71 
     72  int getSizeZ() : 
     73    TODO. 
     74 
     75  int getSizeC() : 
     76    TODO. 
     77 
     78  int getSizeT() : 
     79    TODO. 
     80 
     81  int getEffectiveSizeC() : 
     82    TODO. 
     83 
     84  int getRGBChannelCount() : 
     85    TODO. 
     86 
     87  boolean isRGB() : 
     88    TODO. 
     89 
     90  int getThumbSizeX() : 
     91    TODO. 
     92 
     93  int getThumbSizeY() : 
     94    TODO. 
     95 
     96  int getPixelType() : 
     97    TODO. 
     98 
     99  int[] getChannelDimLengths() : 
     100    TODO. 
     101 
     102  String[] getChannelDimTypes() : 
     103    TODO. 
     104 
     105  String getDimensionOrder() : 
     106    TODO. 
     107 
     108  boolean isOrderCertain() : 
     109    TODO. 
     110 
     111  boolean isLittleEndian() : 
     112    TODO. 
     113 
     114  boolean isInterleaved() : 
     115    TODO. 
     116 
     117  boolean isInterleaved(int) : 
     118    TODO. 
     119 
     120  Hashtable getMetadata() : 
     121    TODO. 
     122 
     123                             II. Original Metadata 
     124                            ----------------------- 
     125 
     126Every format names and organizes its metadata differently. Bio-Formats 
     127preserves this organization and naming structure as much as possible, 
     128transferring all such information into a hashtable filled with key/value 
     129string pairs. You can obtain this hashtable of "original" metadata from the 
     130format reader by calling the getMetadata() method. You can use the format 
     131reader's setMetadataCollected(boolean) method to control whether Bio-Formats 
     132collects the original metadata.  original metadata is collected at all. 
     133 
     134The following methods of IFormatReader relate to original metadata handling: 
     135 
     136  void setMetadataCollected(boolean) : 
     137    Controls whether the format reader collects original metadata at all. 
     138 
     139  boolean isMetadataCollected() : 
     140    Reports whether the format reader is configured to collect original 
     141    metadata. 
     142 
     143  Object getMetadataValue(String) : 
     144    Gets the value correesponding to the given metadata key from the 
     145    original metadata hashtable. This method is a shortcut for calling 
     146    getMetadata().get(String). 
     147 
     148  Hashtable getMetadata() : 
     149    Gets the hashtable (not a copy) containing the original metadata 
     150    key/value pairs. 
     151 
     152  void setMetadataFiltered(boolean) : 
     153    Controls whether metadata pairs with extremely long values or containing 
     154    certain unprintable characters should be filtered out of the results. 
     155    This method is useful to reduce the amount of bloat and unreadable garbage 
     156    in the original metadata list. 
     157 
     158  boolean isMetadataFiltered() : 
     159    Reports whether the format reader is configured to filter out metadata 
     160    pairs with extremely long values or containing certain unprintable 
     161    characters. 
     162 
     163                        III. Standardization to OME-XML 
     164                       --------------------------------- 
     165 
     166While it is handy that Bio-Formats can read the pixels from a large number of 
     167proprietary formats, the library's main purpose is to standardize those 
     168formats' metadata into a single structure: OME-XML. By converting the metadata 
     169into OME-XML, applications can support a single metadata standard, and delegate 
     170the metadata processing for specific third party formats to Bio-Formats. 
     171 
     172For each format, Bio-Formats is currently able to integrate a number of 
     173metadata parameters into the OME-XML schema proper, but every format has a few 
     174that do not fit into the schema, for a variety of reasons. As such, we also 
     175provide functionality to store all the "original" key/value pairs into the 
     176OME-XML structure as custom attributes. 
     177 
     178TODO - Paragraph explaining MetadataStore/MetadataRetrieve API, and how we can 
     179standardize into any metadata standard, not just OME-XML, with the proper 
     180implementation of these interfaces (e.g., OMEROMetadataStore), as well as 
     181feed one metadata standard into another with 
     182MetadataTools.convertMetadata(MetadataRetrieve, MetadataStore). 
     183 
     184TODO - Explain DummyMetadata and AggregateMetadataStore. 
     185 
     186TODO - Explain that there is one implementation per version of the OME-XML 
     187schema (2004 and 2007-06 right now), and that there is code for autogenerating 
     188these implementations in the loci.formats.auto package (though understanding 
     189the autogenerator is certainly "extra credit" and not necessary to use the 
     190metadata API). loci.formats.ome.OMEXMLMetadata is the abstract superclass of 
     191all concrete OME-XML metadata classes. OMEXMLMetadata implements both 
     192MetadataStore and MetadataRetrieve. 
     193 
     194TODO - Explain how we have isolated all dependencies on the OME Java library 
     195(in ome-java.jar) into the loci.formats.ome package, and made that package 
     196optional at compile time, using Java reflection. The loci.formats.MetadataTools 
     197class provides a mechanism to create OME-XML metadata objects without importing 
     198the loci.formats.ome classes directly. 
     199 
     200The following methods of IFormatReader relate to OME-XML metadata processing: 
     201 
     202  void setOriginalMetadataPopulated(boolean) : 
     203    Controls whether Bio-Formats shoehorns the original metadata key/value 
     204    pairs into OME-XML as custom attributes. 
     205 
     206  boolean isOriginalMetadataPopulated() : 
     207    Reports whether Bio-Formats is configured to populate the original 
     208    metadata key/value pairs into OME-XML as custom attributes. 
     209 
     210  void isMetadataComplete() : 
     211    Reports whether we are confident that Bio-Formats fully converts all 
     212    relevant metadata fields into the OME-XML schema. Some metadata-sensitive 
     213    applications (e.g., OMERO) use this when deciding whether to flag a 
     214    particular format as "supported." 
     215 
     216  void setMetadataStore(MetadataStore) : 
     217    TODO. 
     218 
     219  void getMetadataStore() : 
     220    TODO. 
     221 
     222  void getMetadataStoreRoot() : 
     223    TODO. 
     224 
     225The following methods of IFormatWriter relate to OME-XML metadata processing: 
     226 
     227  void setMetadataRetrieve(MetadataRetrieve) : 
     228    Provides a metadata retrieval object to the format writer to use when 
     229    writing that format's metadata. 
     230 
     231  MetadataRetrieve getMetadataRetrieve() : 
     232    Obtains the metadata retrieval object currently associated with the writer. 
     233 
     234MetadataStore methods: 
     235 
     236  TODO - Don't actually list them all; there are too many. 
     237 
     238MetadataRetrieve methods: 
     239 
     240  TODO - Don't actually list them all; there are too many. 
     241 
     242OMEXMLMetadata methods: 
     243 
     244  TODO -  
     245 
     246MetadataTools methods: 
     247 
     248  TODO 
     249 
     250AggregateMetadataStore methods: 
     251 
     252  TODO 
Note: See TracChangeset for help on using the changeset viewer.