Follow-on to asdf-format/asdf-website#15 which mentions that such a document should be added for libasdf, and #202 (comment)
This need not repeat most of the conceptual discussion in the asdf-website page, and focus on concrete examples with reference to CFITSIO (there are other C and FORTRAN FITS codes, often hand-written for specific cases; but CFITSIO is the only relevant and well-documented reference implementation I know of).
Where some "mindset shift" discussion is warranted is how to find specific types of values within an ASDF file, since this is really important for application authors to think about. In most FITS files there are at most one "images", usually either in the primary header or in the first IMAGE extension header, and this is easy for applications to reason about just knowing the structure of FITS. Some FITS files can of course contain multiple images as multiple image extensions, and applications can and do support enumerating and selecting data from extensions. But knowing what IMAGE data is available in a FITS file is very straightforward to reason about from the FITS format itself.
In ASDF the situation is radically different. There is no fixed list of IMAGEs. Rather, there can be zero or more ndarrays in the tree. Whether or not any given ndarray represents an "image" is entirely dependent on the overall data model. Certain software may wish to implement support for known data models, but that's outside the scope for libasdf, at least for now (and lacking a standard astronomy-specific schema for imaging observations). So here an application may wish to enumerate all ndarray in the tree (using asdf_value_find_iter for example, and report their paths.
Furthermore there is no standard for associating an imaging array with some metadata like a WCS. This is also model-dependent. The solutions I took for this in SourceXtractor++ would be worth documenting as a recommendation.
All in all worth further consideration of how this should be handled...
Follow-on to asdf-format/asdf-website#15 which mentions that such a document should be added for libasdf, and #202 (comment)
This need not repeat most of the conceptual discussion in the asdf-website page, and focus on concrete examples with reference to CFITSIO (there are other C and FORTRAN FITS codes, often hand-written for specific cases; but CFITSIO is the only relevant and well-documented reference implementation I know of).
Where some "mindset shift" discussion is warranted is how to find specific types of values within an ASDF file, since this is really important for application authors to think about. In most FITS files there are at most one "images", usually either in the primary header or in the first IMAGE extension header, and this is easy for applications to reason about just knowing the structure of FITS. Some FITS files can of course contain multiple images as multiple image extensions, and applications can and do support enumerating and selecting data from extensions. But knowing what IMAGE data is available in a FITS file is very straightforward to reason about from the FITS format itself.
In ASDF the situation is radically different. There is no fixed list of IMAGEs. Rather, there can be zero or more ndarrays in the tree. Whether or not any given ndarray represents an "image" is entirely dependent on the overall data model. Certain software may wish to implement support for known data models, but that's outside the scope for libasdf, at least for now (and lacking a standard astronomy-specific schema for imaging observations). So here an application may wish to enumerate all ndarray in the tree (using
asdf_value_find_iterfor example, and report their paths.Furthermore there is no standard for associating an imaging array with some metadata like a WCS. This is also model-dependent. The solutions I took for this in SourceXtractor++ would be worth documenting as a recommendation.
All in all worth further consideration of how this should be handled...