added doc example for exif, exif sample tiff and some sad error handling in ifd::from_tags

Author: feefladder

src/ifd.rs

@@ -269,11 +269,17 @@ impl ImageFileDirectory {
                 Tag::Unknown(DOCUMENT_NAME) => document_name = Some(value.into_string()?),
                 t => {
                     if extra_tags_registry.contains(&t) {
-                        extra_tags_registry[&t].process_tag(t, value);
+                        extra_tags_registry[&t].process_tag(t, value).map_err(|e| {
+                            if let AsyncTiffError::InternalTIFFError(err) = e {
+                                err
+                            } else {
+                                // TODO fix error handling. This is bad
+                                TiffError::IntSizeError
+                            }
+                        })?;
                     } else {
                         other_tags.insert(tag, value);
                     }
-
                 }
             };
             Ok::<_, TiffError>(())
@@ -645,6 +651,11 @@ impl ImageFileDirectory {
         self.model_tiepoint.as_deref()
     }
 
+    /// the registry holding extra tags
+    pub fn extra_tags(&self) -> &ExtraTagsRegistry {
+        &self.extra_tags
+    }
+
     /// Tags for which the tiff crate doesn't have a hard-coded enum variant.
     pub fn other_tags(&self) -> &HashMap<Tag, Value> {
         &self.other_tags

src/metadata/extra_tags.rs

@@ -9,18 +9,81 @@ use std::sync::Arc;
 
 /// Trait to implement for custom tags, such as Geo, EXIF, OME, etc
 /// your type should also implement `Clone`
+///
+/// ```
+/// # use std::sync::{LazyLock, OnceLock, Arc};
+/// # use std::env::current_dir;
+/// # use async_tiff::tiff::{Value, tags::Tag};
+/// # use async_tiff::error::AsyncTiffResult;
+/// # use async_tiff::reader::{ObjectReader, AsyncFileReader};
+/// use async_tiff::metadata::{ExtraTags, ExtraTagsRegistry, TiffMetadataReader};
+/// # use object_store::local::LocalFileSystem;
+/// // see https://www.media.mit.edu/pia/Research/deepview/exif.html#ExifTags
+/// // or exif spec: https://www.cipa.jp/std/documents/download_e.html?DC-008-Translation-2023-E
+/// // / all tags processed by your extension
+/// pub static EXIF_TAGS: LazyLock<Vec<Tag>> = LazyLock::new(|| vec![
+///     Tag::Unknown(34665), // Exif IFD pointer
+///     Tag::Unknown(34853), // GPS IFD pointer
+///     Tag::Unknown(40965), // Interoperability IFD pointer
+/// ]);
+///
+/// // / the struct that stores the data (using interior mutability)
+/// #[derive(Debug, Clone, Default)]
+/// pub struct ExifTags {
+///     pub exif: OnceLock<u32>,
+///     pub gps: OnceLock<u32>,
+///     pub interop: OnceLock<u32>,
+/// }
+///
+/// impl ExtraTags for ExifTags {
+///     fn tags(&self) -> &'static [Tag] {
+///          &EXIF_TAGS
+///     }
+///
+///     fn process_tag(&self, tag:Tag, value: Value) -> AsyncTiffResult<()> {
+///         match tag {
+///             Tag::Unknown(34665) => self.exif.set(value.into_u32()?).unwrap(),
+///             Tag::Unknown(34853) => self.gps.set(value.into_u32()?).unwrap(),
+///             Tag::Unknown(40965) => self.interop.set(value.into_u32()?).unwrap(),
+///             _ => {}
+///         }
+///         Ok(())
+///     }
+/// }
+///
+/// #[tokio::main]
+/// async fn main() {
+///     let mut registry = ExtraTagsRegistry::new();
+///     registry.register(Arc::new(ExifTags::default()));
+/// #   let store = Arc::new(LocalFileSystem::new_with_prefix(current_dir().unwrap()).unwrap());
+/// #   let path = "tests/sample-exif.tiff";
+///     let reader = Arc::new(ObjectReader::new(store.clone(), path.into())) as Arc<dyn AsyncFileReader>;
+///     let mut metadata_reader = TiffMetadataReader::try_open(&reader).await.unwrap();
+///     let ifd = metadata_reader.read_next_ifd(&reader, registry).await.unwrap().unwrap();
+///     // access by any of our registered tags
+///     let exif = ifd.extra_tags()[&EXIF_TAGS[0]].clone().as_any_arc().downcast::<ExifTags>().unwrap();
+///     assert!(exif.exif.get().is_some());
+///     assert!(exif.gps.get().is_some());
+///     // our image doesn't have interop info
+///     assert!(exif.interop.get().is_none());
+/// }
+/// ```
 // Send + Sync are required for Python, where `dyn ExtraTags` needs `Send` and `Sync`
 pub trait ExtraTags: ExtraTagsBlankets + Any + Debug + Send + Sync {
     /// a list of tags this entry processes
+    ///
     /// e.g. for Geo this would be [34735, 34736, 34737]
     fn tags(&self) -> &'static [Tag];
     /// process a single tag, using internal mutability if needed
     fn process_tag(&self, tag: Tag, value: Value) -> AsyncTiffResult<()>;
 }
 
 // we need to do a little dance to do an object-safe deep clone
-// https://stackoverflow.com/a/30353928/14681457
-// also object-safe type conversions for downcasting
+// https://stackoverflow.com/a/30353928/14681457 also object-safe type
+// conversions for downcasting.
+//
+// This works since blanket implementations are done on concrete types and only
+// their signatures (function pointer) will end up in the vtable
 pub trait ExtraTagsBlankets {
     fn clone_arc(&self) -> Arc<dyn ExtraTags>;
     fn as_any_arc(self: Arc<Self>) -> Arc<dyn Any + Send + Sync>;