Add tests and documentation for BMFF support (fixes #48)

- Support for BMFF files (HEIC, HEIF, AVIF, CR3, JXL/bmff) was already available. However, the initialize function needed to get called for it to work. Also the dependencies need to be correct. This should now be clearer in the tests and documentation

Author: NoxHarmonium

README.md

@@ -60,6 +60,11 @@ gexiv2 is supported from version 0.10 onwards, and Exiv2 from version 0.23.
 For full instructions on how to get started with rexiv2, including how to
 install the prerequisite dependencies, refer to the [`SETUP`](SETUP.md) file.
 
+Note that if you want BMFF support (e.g. HEIC, HEIF, AVIF, CR3, JXL/bmff files)
+you will need an up to date version of the underlying libraries (gexiv2 v0.13.0 and Exiv2 v0.27.4).
+You will also need to ensure that your version of Exiv2 has BMFF support enabled.
+This is generally enabled by default, but may be switched off in certain distributions
+due to licensing issues.
 
 Versioning & History
 --------------------

examples/gps.rs

@@ -3,6 +3,8 @@ extern crate rexiv2;
 use rexiv2::Metadata;
 
 fn main() {
+    rexiv2::initialize().expect("Unable to initialize rexiv2");
+
     if let Ok(meta) = Metadata::new_from_path("examples/example.jpg") {
         if let Some(location) = meta.get_gps_info() {
             println!("Location: {:?}", location);

examples/timestamp.rs

@@ -3,6 +3,8 @@ extern crate rexiv2;
 use rexiv2::Metadata;
 
 fn main() {
+    rexiv2::initialize().expect("Unable to initialize rexiv2");
+
     if let Ok(meta) = Metadata::new_from_path("examples/example.jpg") {
         if let Ok(time) = meta.get_tag_string("Exif.Image.DateTime") {
             println!("Time: {:?}", time);

src/lib.rs

@@ -1021,25 +1021,33 @@ pub fn get_tag_type(tag: &str) -> Result<TagType> {
 
 /// Initialize gexiv2.
 ///
-/// This must be called in a thread-safe fashion before using rexiv2 in
-/// multi-threaded applications.
+/// This must be called in a thread-safe fashion before using rexiv2.
+/// The library may appear to work without calling this, but some
+/// features such as HEIC/BMFF will silently fail, and the underlying
+/// libraries make the assumption that this will be called so it
+/// is safer to do so.
+///
+/// Calling it first thing in the main function should ensure that
+/// it is executed on the main thread and is thread safe. Do not call
+/// it in a threaded or async context (such as in a tokio context).
+///
+/// # See also
+///
+/// Associated Gexiv2 Source Code: https://gitlab.gnome.org/GNOME/gexiv2/-/blob/e4d65b31cd77f28ef248117e161de9d8cc31d712/gexiv2/gexiv2-startup.cpp#L14
+///
+/// # Examples
+///
+/// Simple call at the start of the application
 ///
-/// # Example
 /// ```
-/// use std::sync::{Once, ONCE_INIT};
 /// fn main() {
-///     static START: Once = ONCE_INIT;
-///
-///     START.call_once(|| unsafe {
-///         rexiv2::initialize().expect("Unable to initialize rexiv2");
-///     });
+///     rexiv2::initialize().expect("Unable to initialize rexiv2");
 /// }
 /// ```
 pub fn initialize() -> Result<()> {
     unsafe { int_bool_to_result(gexiv2::gexiv2_initialize()) }
 }
 
-
 // XMP namespace management.
 
 /// Add a new XMP namespace for tags to exist under.

tst/main.rs

@@ -17,29 +17,48 @@ extern crate rexiv2;
 
 use std::path::Path;
 
+use std::sync::Once;
+
+static INIT: Once = Once::new();
+
+///
+/// Should be called before any test runs. Will ensure that the library is initialized at most once.
+/// This would be the equivalent of a "beforeAll" function in other test libraries.
+///
+/// Future work: At some strange it might be good to work out if this can be done automatically
+/// by the test runner. It doesn't seem to be right now with the stock cargo test runner but
+/// it might be possible with 3rd party crates.
+///
+fn setup_test() {
+    INIT.call_once(|| rexiv2::initialize().expect("Unable to initialize rexiv2"));
+}
 
 #[test]
 fn new_from_str_path() {
+    setup_test();
     let sample_path = concat!(env!("CARGO_MANIFEST_DIR"), "/tst/sample.png");
     let meta = rexiv2::Metadata::new_from_path(sample_path).unwrap();
     assert_eq!(meta.get_media_type().unwrap(), rexiv2::MediaType::Png);
 }
 
 #[test]
 fn new_from_path() {
+    setup_test();
     let sample_path = Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/tst/sample.png"));
     let meta = rexiv2::Metadata::new_from_path(sample_path).unwrap();
     assert_eq!(meta.get_media_type().unwrap(), rexiv2::MediaType::Png);
 }
 
 #[test]
 fn new_from_buffer() {
+    setup_test();
     let meta = rexiv2::Metadata::new_from_buffer(include_bytes!("sample.png")).unwrap();
     assert_eq!(meta.get_media_type().unwrap(), rexiv2::MediaType::Png);
 }
 
 #[test]
 fn new_from_buffer_error() {
+    setup_test();
     let mut bytes = include_bytes!("sample.png").to_vec();
     bytes.swap(0, 1);
     let meta_result = rexiv2::Metadata::new_from_buffer(&bytes);
@@ -53,24 +72,49 @@ fn new_from_buffer_error() {
 
 #[test]
 fn supports_exif() {
+    setup_test();
     let meta = rexiv2::Metadata::new_from_buffer(include_bytes!("sample.png")).unwrap();
     assert_eq!(meta.supports_exif(), true);
 }
 
 #[test]
 fn supports_iptc() {
+    setup_test();
     let meta = rexiv2::Metadata::new_from_buffer(include_bytes!("sample.png")).unwrap();
     assert_eq!(meta.supports_iptc(), true);
 }
 
 #[test]
 fn supports_xmp() {
+    setup_test();
     let meta = rexiv2::Metadata::new_from_buffer(include_bytes!("sample.png")).unwrap();
     assert_eq!(meta.supports_xmp(), true);
 }
 
+#[test]
+fn supports_bmff() {
+    setup_test();
+    // iPhone devices use the HEIC (BMFF) file format which only works properly after gexiv2 has been initialized
+    // (and the underlying libraries are the right version gexiv2 v0.13.0/Exiv2 v0.27.4)
+    // I copied a photo off an iPhone and shrunk it down to ensure that reading tags works
+
+    let meta = rexiv2::Metadata::new_from_buffer(include_bytes!("sample.HEIC")).unwrap();
+    let gps = meta.get_gps_info().unwrap();
+    assert_eq!(gps.latitude as i32, -27);
+    assert_eq!(gps.longitude as i32, 114);
+    let phone_model = meta.get_tag_string("Exif.Image.Model").unwrap();
+    assert_eq!(phone_model, "iPhone XS");
+
+    // This seems strange since we can read the above information
+    // We may be missing a "supports" function for bmff tags, or the functions may be returning incorrectly
+    assert_eq!(meta.supports_exif(), false);
+    assert_eq!(meta.supports_iptc(), false);
+    assert_eq!(meta.supports_xmp(), false);
+}
+
 #[test]
 fn log_levels() {
+    setup_test();
     assert_eq!(rexiv2::get_log_level(), rexiv2::LogLevel::WARN);
     rexiv2::set_log_level(rexiv2::LogLevel::INFO);
     assert_eq!(rexiv2::get_log_level(), rexiv2::LogLevel::INFO);
@@ -79,6 +123,7 @@ fn log_levels() {
 #[test]
 #[cfg(feature = "raw-tag-access")]
 fn get_tag_raw() {
+    setup_test();
     let meta = rexiv2::Metadata::new_from_buffer(include_bytes!("sample.png")).unwrap();
     meta.set_tag_string("Exif.Image.DateTime", "2020:07:12 11:16:35")
         .unwrap();