@capawesome/capacitor-exif 0.0.1 → 0.1.0

package/README.md

@@ -23,9 +23,14 @@ Capacitor plugin to read, write and remove EXIF metadata from image files.
 
 Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
 
-## Newsletter
+## Use Cases
 
-Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+The Exif plugin is typically used whenever an app needs to work with photo metadata, for example:
+
+- **Privacy protection**: Strip GPS positions and other sensitive metadata from photos before uploading them to a server.
+- **Photo organization**: Read the capture date and GPS position to sort and group photos.
+- **Metadata correction**: Fix a wrong capture date or add a missing GPS position without re-encoding the image.
+- **Camera details**: Display camera and lens information such as ISO, aperture, and exposure time in a photo detail view.
 
 ## Compatibility
 
@@ -73,6 +78,12 @@ No configuration required for this plugin.
 
 ## Usage
 
+The following examples show how to read the EXIF metadata of an image, write EXIF tags to an image, and remove the EXIF metadata from an image.
+
+### Read the EXIF metadata of an image
+
+Read typed EXIF tags such as the GPS position, camera model, and capture date from an image file. Only available on Android and iOS:
+
 ```typescript
 import { Exif } from '@capawesome/capacitor-exif';
 
@@ -82,6 +93,14 @@ const readExif = async () => {
   });
   console.log('GPS position:', tags.gpsLatitude, tags.gpsLongitude);
 };
+```
+
+### Write EXIF tags to an image
+
+Update EXIF tags in place. Only the provided tags are updated and the pixel data is never re-encoded. Only available on Android and iOS:
+
+```typescript
+import { Exif } from '@capawesome/capacitor-exif';
 
 const writeExif = async () => {
   await Exif.writeExif({
@@ -93,6 +112,14 @@ const writeExif = async () => {
     },
   });
 };
+```
+
+### Remove the EXIF metadata from an image
+
+Strip all EXIF metadata from an image file in place, for example to protect the privacy of your users before an upload. By default, the orientation tag is kept so that the image is not suddenly displayed rotated. Only available on Android and iOS:
+
+```typescript
+import { Exif } from '@capawesome/capacitor-exif';
 
 const removeExif = async () => {
   await Exif.removeExif({
@@ -313,6 +340,47 @@ const prepareUpload = async (path: string) => {
 - HEIC files store the orientation at the container level, so the `orientation` tag can not be changed and is always kept, even with `keepOrientation` set to `false`.
 - HEIC files may keep the `software` and `dateTimeOriginal` tags after `removeExif(...)`. GPS data and device identity tags (`make`, `model`, `lensModel`) are always removed.
 
+## FAQ
+
+### How is this plugin different from other similar plugins?
+
+It reads, writes and removes EXIF metadata directly on the image file on Android and iOS, updating tags in place so the pixel data is never re-encoded and the image quality is untouched. It reads and writes HEIC metadata natively, processes files natively without loading them into WebView memory, and uses only official platform APIs, so it stays App Store safe. The API is fully typed, ships for both CocoaPods and Swift Package Manager, and is kept current with the latest Capacitor version.
+
+### Which platforms are supported by this plugin?
+
+The plugin supports Android and iOS. All methods (`readExif`, `writeExif` and `removeExif`) are only available on these two platforms, since the files are processed natively and never loaded into the WebView memory.
+
+### Does writing or removing EXIF metadata affect the image quality?
+
+No. Writing and removing EXIF metadata is a lossless in-place operation. The pixel data is never decoded or re-encoded, so the image quality is not affected. See [Lossless Metadata Writes](#lossless-metadata-writes) for details on how this is implemented on each platform.
+
+### Which image formats are supported?
+
+Reading EXIF metadata works with any image format that the platform supports, including JPEG, PNG, WebP, HEIC/HEIF, and DNG/RAW. Writing and removing metadata is only supported for certain formats, which differ between Android and iOS (see [Format Support](#format-support)). Calling `writeExif(...)` or `removeExif(...)` with an unsupported format rejects with the `UNSUPPORTED_FORMAT` error code.
+
+### Why is the orientation tag still present after calling `removeExif`?
+
+The `keepOrientation` option is enabled by default so that images are not suddenly displayed rotated after the metadata has been removed. You can set it to `false` to also remove the orientation tag. Note that HEIC files on iOS store the orientation at the container level, so it is always kept there.
+
+### How do I remove the GPS position from a photo before uploading it?
+
+Call `removeExif(...)` with the path to the image file. This strips the GPS position along with all other EXIF metadata in place, without affecting the image quality. See [Privacy: Strip Metadata Before Upload](#privacy-strip-metadata-before-upload) for an example.
+
+### Can I use this plugin with Ionic, React, Vue or Angular?
+
+Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
+
+## Related Plugins
+
+- [File Picker](https://capawesome.io/docs/sdks/capacitor/file-picker/): Pick the image files whose metadata you want to read or edit.
+- [File Compressor](https://capawesome.io/docs/sdks/capacitor/file-compressor/): Compress images in formats like PNG, JPEG, and WebP.
+- [Photo Editor](https://capawesome.io/docs/sdks/capacitor/photo-editor/): Let the user edit a photo.
+- [Photo Manipulator](https://capawesome.io/docs/sdks/capacitor/photo-manipulator/): Headless image transforms like crop, resize, rotate, and format conversion.
+
+## Newsletter
+
+Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/exif/CHANGELOG.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capawesome/capacitor-exif",
-  "version": "0.0.1",
-  "description": "Capacitor plugin to read, write and remove EXIF metadata from image files.",
+  "version": "0.1.0",
+  "description": "Capacitor plugin to read, write and remove EXIF metadata from image files on Android and iOS.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
@@ -38,12 +38,21 @@
     "capacitor",
     "plugin",
     "native",
+    "capacitor-plugin",
     "exif",
     "metadata",
     "gps",
     "privacy",
     "heic",
-    "jpeg"
+    "jpeg",
+    "exif metadata",
+    "image metadata",
+    "photo metadata",
+    "exif reader",
+    "exif editor",
+    "remove exif",
+    "strip metadata",
+    "geotag"
   ],
   "scripts": {
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",