Add comprehensive documentation for EXIF metadata and HEIC support requirements

Co-authored-by: moooyo <42196638+moooyo@users.noreply.github.com>

.github/actions/spell-check/expect.txt

@@ -29,6 +29,7 @@ admx
 advancedpaste
 advapi
 advfirewall
+avif
 AFeature
 affordances
 AFX
@@ -350,6 +351,7 @@ DBPROPIDSET
 DBPROPSET
 DCBA
 DCOM
+dng
 DComposition
 DCR
 DDEIf
@@ -653,6 +655,8 @@ hcursor
 hcwhite
 hdc
 hdr
+heic
+heif
 hdrop
 hdwwiz
 Helpline
@@ -1973,6 +1977,7 @@ wdp
 wdupenv
 webbrowsers
 webpage
+webp
 websites
 wekyb
 wft

_codeql_detected_source_root

@@ -0,0 +1 @@
+.

doc/devdocs/modules/powerrename.md

@@ -87,6 +87,63 @@ PowerRename uses WinUI 3 for its user interface. The UI allows users to:
 - Settings panel for configuring rename options
 - Event handling for `SearchReplaceChanged` to update the preview in real-time
 
+## EXIF Metadata Support
+
+PowerRename supports using EXIF metadata from image files in rename patterns. Users can insert metadata fields like `$CAMERA_MAKE`, `$CAMERA_MODEL`, `$ISO`, `$DATE_TAKEN_YYYY`, etc. in the replace field to rename files based on their embedded metadata.
+
+### Supported Image Formats
+
+The metadata extraction feature uses Windows Imaging Component (WIC) and supports the following formats:
+
+| Format | Extensions | Requirements | Metadata Types |
+|--------|-----------|--------------|----------------|
+| JPEG | `.jpg`, `.jpeg` | Built-in | EXIF, XMP, GPS, IPTC |
+| TIFF | `.tif`, `.tiff` | Built-in | EXIF, XMP, GPS, IPTC |
+| PNG | `.png` | Built-in | Text chunks |
+| HEIC/HEIF | `.heic`, `.heif` | Requires codec installation | EXIF, XMP |
+| WebP | `.webp` | Windows 10 1809+ | EXIF, XMP |
+| AVIF | `.avif` | Requires codec installation | EXIF, XMP |
+| JPEG XR | `.jxr`, `.wdp` | Built-in | EXIF, XMP |
+| DNG | `.dng` | Built-in | EXIF, XMP |
+
+### Installing Image Codec Support
+
+Some modern image formats require additional codecs to be installed on Windows:
+
+#### HEIC/HEIF Support (iPhone/iOS images)
+
+1. **Windows 10/11**: Install [HEIF Image Extensions](https://www.microsoft.com/store/productId/9PMMSR1CGPWG) from the Microsoft Store
+   - This is a free extension from Microsoft
+   - Alternatively, you can install the paid version [HEVC Video Extensions](https://www.microsoft.com/store/productId/9NMZLZ57R3T7) which also includes HEIF support
+2. After installation, Windows can decode HEIC/HEIF files for thumbnail generation, preview, and metadata extraction
+3. PowerRename will automatically extract EXIF data from HEIC files once the codec is installed
+
+#### AVIF Support
+
+1. **Windows 10/11**: Install [AV1 Video Extension](https://www.microsoft.com/store/productId/9MVZQVXJBQ9V) from the Microsoft Store
+   - Free extension from Microsoft
+   - Note: HEIF Image Extensions (mentioned above) also provides AVIF decoding support
+2. After installation, PowerRename can extract metadata from AVIF files
+
+### How It Works
+
+1. When a user includes metadata patterns (e.g., `$CAMERA_MAKE`) in the replace field, PowerRename checks if the file format supports metadata extraction
+2. The file extension is checked against the supported formats list in [`Helpers.cpp::isMetadataUsed()`](/src/modules/powerrename/lib/Helpers.cpp)
+3. If supported, [`WICMetadataExtractor`](/src/modules/powerrename/lib/WICMetadataExtractor.cpp) uses WIC to create a decoder for the file
+4. Metadata is extracted using WIC's metadata query reader interface
+5. The extracted values are cached in [`MetadataResultCache`](/src/modules/powerrename/lib/MetadataResultCache.cpp) for performance
+6. The metadata patterns in the filename are replaced with actual values
+
+### Troubleshooting Metadata Extraction
+
+If metadata patterns are not being replaced (e.g., `$CAMERA_MAKE` stays as-is in the filename):
+
+1. **Check file format support**: Verify the file extension is in the supported list above
+2. **Install required codecs**: For HEIC/AVIF files, ensure the required extensions are installed from Microsoft Store
+3. **Verify metadata exists**: Not all images contain EXIF data. Use Windows File Explorer properties to check if metadata is present
+4. **Check file permissions**: Ensure PowerRename has read access to the file
+5. **Review debug logs**: In debug builds, WIC decoder errors are logged to the debug output
+
 ## Debugging
 
 ### Debugging the Context Menu

src/modules/powerrename/lib/Helpers.cpp

@@ -345,16 +345,28 @@ bool isMetadataUsed(_In_ PCWSTR source, PowerRenameLib::MetadataType metadataTyp
         // Convert to lowercase for case-insensitive comparison
         std::transform(extension.begin(), extension.end(), extension.begin(), ::towlower);
 
-        // According to the metadata support table, only these formats support metadata extraction:
+        // Formats that support metadata extraction via WIC (Windows Imaging Component):
         // - JPEG (IFD, Exif, XMP, GPS, IPTC) - supports fast metadata encoding
         // - TIFF (IFD, Exif, XMP, GPS, IPTC) - supports fast metadata encoding  
         // - PNG (text chunks)
+        // - HEIC/HEIF (Exif, XMP) - requires HEIF Image Extensions on Windows 10/11
+        // - WebP (Exif, XMP) - supported natively on Windows 10 1809+
+        // - AVIF (Exif, XMP) - requires HEIF Image Extensions (or AV1 Video Extension) on Windows 10/11
+        // - JPEG XR/HD Photo (Exif, XMP)
+        // - DNG (Digital Negative RAW format - Exif, XMP)
         static const std::unordered_set<std::wstring> supportedExtensions = {
             L".jpg",
             L".jpeg",
             L".png",
             L".tif",
-            L".tiff"
+            L".tiff",
+            L".heic",
+            L".heif",
+            L".webp",
+            L".avif",
+            L".jxr",
+            L".wdp",
+            L".dng"
         };
 
         // If file type doesn't support metadata, no need to check patterns

src/modules/powerrename/unittests/HelpersTests.cpp

@@ -830,4 +830,87 @@ namespace HelpersTests
             Assert::AreEqual(L"file_15EER", result);
         }
     };
+
+    TEST_CLASS(IsMetadataUsedTests)
+    {
+    public:
+        TEST_METHOD(HEIC_Files_Support_Metadata)
+        {
+            // Test that HEIC files are recognized as supporting metadata
+            bool result = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\IMG_1234.heic", false);
+            Assert::IsTrue(result, L"HEIC files should support EXIF metadata");
+        }
+
+        TEST_METHOD(HEIF_Files_Support_Metadata)
+        {
+            // Test that HEIF files are recognized as supporting metadata
+            bool result = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\IMG_1234.heif", false);
+            Assert::IsTrue(result, L"HEIF files should support EXIF metadata");
+        }
+
+        TEST_METHOD(WebP_Files_Support_Metadata)
+        {
+            // Test that WebP files are recognized as supporting metadata
+            bool result = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\image.webp", false);
+            Assert::IsTrue(result, L"WebP files should support EXIF metadata");
+        }
+
+        TEST_METHOD(AVIF_Files_Support_Metadata)
+        {
+            // Test that AVIF files are recognized as supporting metadata
+            bool result = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\image.avif", false);
+            Assert::IsTrue(result, L"AVIF files should support EXIF metadata");
+        }
+
+        TEST_METHOD(DNG_Files_Support_Metadata)
+        {
+            // Test that DNG (Digital Negative RAW) files are recognized as supporting metadata
+            bool result = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\DSC_1234.dng", false);
+            Assert::IsTrue(result, L"DNG files should support EXIF metadata");
+        }
+
+        TEST_METHOD(JPEG_XR_Files_Support_Metadata)
+        {
+            // Test that JPEG XR files are recognized as supporting metadata
+            bool result = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\image.jxr", false);
+            Assert::IsTrue(result, L"JXR files should support EXIF metadata");
+        }
+
+        TEST_METHOD(Case_Insensitive_Extension_Check)
+        {
+            // Test that extension check is case-insensitive
+            bool result1 = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\IMG_1234.HEIC", false);
+            bool result2 = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\IMG_1234.HeIc", false);
+            Assert::IsTrue(result1, L"HEIC extension check should be case-insensitive (uppercase)");
+            Assert::IsTrue(result2, L"HEIC extension check should be case-insensitive (mixed case)");
+        }
+
+        TEST_METHOD(Unsupported_Format_Returns_False)
+        {
+            // Test that unsupported file formats return false
+            bool result = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Documents\\file.txt", false);
+            Assert::IsFalse(result, L"TXT files should not support EXIF metadata");
+        }
+
+        TEST_METHOD(Folders_Do_Not_Support_Metadata)
+        {
+            // Test that folders don't support metadata even with image extensions
+            bool result = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\vacation.heic", true);
+            Assert::IsFalse(result, L"Folders should not support metadata extraction");
+        }
+
+        TEST_METHOD(No_Metadata_Pattern_Returns_False)
+        {
+            // Test that even supported formats return false if no metadata pattern is in the search term
+            bool result = isMetadataUsed(L"vacation", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\IMG_1234.heic", false);
+            Assert::IsFalse(result, L"Should return false when no metadata pattern is present");
+        }
+
+        TEST_METHOD(Traditional_JPEG_Still_Supported)
+        {
+            // Test that traditional JPEG files still work
+            bool result = isMetadataUsed(L"$CAMERA_MAKE", PowerRenameLib::MetadataType::EXIF, L"C:\\Photos\\photo.jpg", false);
+            Assert::IsTrue(result, L"JPEG files should support EXIF metadata");
+        }
+    };
 }