@capgo/camera-preview 7.4.0-beta.2 → 7.4.0-beta.4

package/README.md

@@ -92,6 +92,52 @@ Then run
 npx cap sync
 ```
 
+## Optional Configuration
+
+To use certain features of this plugin, you will need to add the following permissions/keys to your native project configurations.
+
+### Android
+
+In your `android/app/src/main/AndroidManifest.xml`:
+
+- **Audio Recording** (`disableAudio: false`):
+  ```xml
+  <uses-permission android:name="android.permission.RECORD_AUDIO" />
+  ```
+
+- **Saving to Gallery** (`saveToGallery: true`):
+  ```xml
+  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+  ```
+
+- **Location in EXIF Data** (`withExifLocation: true`):
+  ```xml
+  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+  ```
+
+### iOS
+
+In your `ios/App/App/Info.plist`, you must provide descriptions for the permissions your app requires. The keys are added automatically, but you need to provide the `string` values.
+
+- **Audio Recording** (`disableAudio: false`):
+  ```xml
+  <key>NSMicrophoneUsageDescription</key>
+  <string>To record audio with videos</string>
+  ```
+
+- **Saving to Gallery** (`saveToGallery: true`):
+  ```xml
+  <key>NSPhotoLibraryAddUsageDescription</key>
+  <string>To save photos to your gallery</string>
+  ```
+
+- **Location in EXIF Data** (`withExifLocation: true`):
+  ```xml
+  <key>NSLocationWhenInUseUsageDescription</key>
+  <string>To add location data to your photos</string>
+  ```
+
 ## Extra Android installation steps
 
 **Important** `camera-preview` 3+ requires Gradle 7.
@@ -174,6 +220,8 @@ Documentation for the [uploader](https://github.com/Cap-go/capacitor-uploader)
 * [`capture(...)`](#capture)
 * [`captureSample(...)`](#capturesample)
 * [`getSupportedFlashModes()`](#getsupportedflashmodes)
+* [`setAspectRatio(...)`](#setaspectratio)
+* [`getAspectRatio()`](#getaspectratio)
 * [`getHorizontalFov()`](#gethorizontalfov)
 * [`getSupportedPictureSizes()`](#getsupportedpicturesizes)
 * [`setFlashMode(...)`](#setflashmode)
@@ -203,7 +251,7 @@ The main interface for the CameraPreview plugin.
 ### start(...)
 
 ```typescript
-start(options: CameraPreviewOptions) => Promise<void>
+start(options: CameraPreviewOptions) => Promise<{ width: number; height: number; x: number; y: number; }>
 ```
 
 Starts the camera preview.
@@ -212,6 +260,8 @@ Starts the camera preview.
 | ------------- | --------------------------------------------------------------------- | ------------------------------------------- |
 | **`options`** | <code><a href="#camerapreviewoptions">CameraPreviewOptions</a></code> | - The configuration for the camera preview. |
 
+**Returns:** <code>Promise&lt;{ width: number; height: number; x: number; y: number; }&gt;</code>
+
 **Since:** 0.0.1
 
 --------------------
@@ -283,6 +333,38 @@ Gets the flash modes supported by the active camera.
 --------------------
 
 
+### setAspectRatio(...)
+
+```typescript
+setAspectRatio(options: { aspectRatio: '4:3' | '16:9' | 'fill'; }) => Promise<void>
+```
+
+Set the aspect ratio of the camera preview.
+
+| Param         | Type                                                     | Description                 |
+| ------------- | -------------------------------------------------------- | --------------------------- |
+| **`options`** | <code>{ aspectRatio: '4:3' \| '16:9' \| 'fill'; }</code> | - The desired aspect ratio. |
+
+**Since:** 7.4.0
+
+--------------------
+
+
+### getAspectRatio()
+
+```typescript
+getAspectRatio() => Promise<{ aspectRatio: '4:3' | '16:9' | 'fill'; }>
+```
+
+Gets the current aspect ratio of the camera preview.
+
+**Returns:** <code>Promise&lt;{ aspectRatio: '4:3' | '16:9' | 'fill'; }&gt;</code>
+
+**Since:** 7.4.0
+
+--------------------
+
+
 ### getHorizontalFov()
 
 ```typescript
@@ -522,28 +604,30 @@ Gets the ID of the currently active camera device.
 
 Defines the configuration options for starting the camera preview.
 
-| Prop                               | Type                 | Description                                                                                                       | Default             |
-| ---------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------- |
-| **`parent`**                       | <code>string</code>  | The parent element to attach the video preview to.                                                                |                     |
-| **`className`**                    | <code>string</code>  | A CSS class name to add to the preview element.                                                                   |                     |
-| **`width`**                        | <code>number</code>  | The width of the preview in pixels. Defaults to the screen width.                                                 |                     |
-| **`height`**                       | <code>number</code>  | The height of the preview in pixels. Defaults to the screen height.                                               |                     |
-| **`x`**                            | <code>number</code>  | The horizontal origin of the preview, in pixels.                                                                  |                     |
-| **`y`**                            | <code>number</code>  | The vertical origin of the preview, in pixels.                                                                    |                     |
-| **`includeSafeAreaInsets`**        | <code>boolean</code> | Adjusts the y-position to account for safe areas (e.g., notches).                                                 | <code>false</code>  |
-| **`toBack`**                       | <code>boolean</code> | If true, places the preview behind the webview.                                                                   | <code>true</code>   |
-| **`paddingBottom`**                | <code>number</code>  | Bottom padding for the preview, in pixels.                                                                        |                     |
-| **`rotateWhenOrientationChanged`** | <code>boolean</code> | Whether to rotate the preview when the device orientation changes.                                                | <code>true</code>   |
-| **`position`**                     | <code>string</code>  | The camera to use.                                                                                                | <code>"rear"</code> |
-| **`storeToFile`**                  | <code>boolean</code> | If true, saves the captured image to a file and returns the file path. If false, returns a base64 encoded string. | <code>false</code>  |
-| **`disableExifHeaderStripping`**   | <code>boolean</code> | If true, prevents the plugin from rotating the image based on EXIF data.                                          | <code>false</code>  |
-| **`enableHighResolution`**         | <code>boolean</code> | If true, enables high-resolution image capture.                                                                   | <code>false</code>  |
-| **`disableAudio`**                 | <code>boolean</code> | If true, disables the audio stream, preventing audio permission requests.                                         | <code>false</code>  |
-| **`lockAndroidOrientation`**       | <code>boolean</code> | If true, locks the device orientation while the camera is active.                                                 | <code>false</code>  |
-| **`enableOpacity`**                | <code>boolean</code> | If true, allows the camera preview's opacity to be changed.                                                       | <code>false</code>  |
-| **`enableZoom`**                   | <code>boolean</code> | If true, enables pinch-to-zoom functionality on the preview.                                                      | <code>false</code>  |
-| **`enableVideoMode`**              | <code>boolean</code> | If true, uses the video-optimized preset for the camera session.                                                  | <code>false</code>  |
-| **`deviceId`**                     | <code>string</code>  | The `deviceId` of the camera to use. If provided, `position` is ignored.                                          |                     |
+| Prop                               | Type                                          | Description                                                                                                        | Default             | Since |
+| ---------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------- | ----- |
+| **`parent`**                       | <code>string</code>                           | The parent element to attach the video preview to.                                                                 |                     |       |
+| **`className`**                    | <code>string</code>                           | A CSS class name to add to the preview element.                                                                    |                     |       |
+| **`width`**                        | <code>number</code>                           | The width of the preview in pixels. Defaults to the screen width.                                                  |                     |       |
+| **`height`**                       | <code>number</code>                           | The height of the preview in pixels. Defaults to the screen height.                                                |                     |       |
+| **`x`**                            | <code>number</code>                           | The horizontal origin of the preview, in pixels.                                                                   |                     |       |
+| **`y`**                            | <code>number</code>                           | The vertical origin of the preview, in pixels.                                                                     |                     |       |
+| **`aspectRatio`**                  | <code>'4:3' \| '16:9' \| 'fill'</code>        | The aspect ratio of the camera preview, '4:3' or '16:9'. If not set, the camera will use the default aspect ratio. |                     | 2.0.0 |
+| **`gridMode`**                     | <code><a href="#gridmode">GridMode</a></code> | The grid overlay to display on the camera preview.                                                                 | <code>"none"</code> | 2.1.0 |
+| **`includeSafeAreaInsets`**        | <code>boolean</code>                          | Adjusts the y-position to account for safe areas (e.g., notches).                                                  | <code>false</code>  |       |
+| **`toBack`**                       | <code>boolean</code>                          | If true, places the preview behind the webview.                                                                    | <code>true</code>   |       |
+| **`paddingBottom`**                | <code>number</code>                           | Bottom padding for the preview, in pixels.                                                                         |                     |       |
+| **`rotateWhenOrientationChanged`** | <code>boolean</code>                          | Whether to rotate the preview when the device orientation changes.                                                 | <code>true</code>   |       |
+| **`position`**                     | <code>string</code>                           | The camera to use.                                                                                                 | <code>"rear"</code> |       |
+| **`storeToFile`**                  | <code>boolean</code>                          | If true, saves the captured image to a file and returns the file path. If false, returns a base64 encoded string.  | <code>false</code>  |       |
+| **`disableExifHeaderStripping`**   | <code>boolean</code>                          | If true, prevents the plugin from rotating the image based on EXIF data.                                           | <code>false</code>  |       |
+| **`enableHighResolution`**         | <code>boolean</code>                          | If true, enables high-resolution image capture.                                                                    | <code>false</code>  |       |
+| **`disableAudio`**                 | <code>boolean</code>                          | If true, disables the audio stream, preventing audio permission requests.                                          | <code>true</code>   |       |
+| **`lockAndroidOrientation`**       | <code>boolean</code>                          | If true, locks the device orientation while the camera is active.                                                  | <code>false</code>  |       |
+| **`enableOpacity`**                | <code>boolean</code>                          | If true, allows the camera preview's opacity to be changed.                                                        | <code>false</code>  |       |
+| **`enableZoom`**                   | <code>boolean</code>                          | If true, enables pinch-to-zoom functionality on the preview.                                                       | <code>false</code>  |       |
+| **`enableVideoMode`**              | <code>boolean</code>                          | If true, uses the video-optimized preset for the camera session.                                                   | <code>false</code>  |       |
+| **`deviceId`**                     | <code>string</code>                           | The `deviceId` of the camera to use. If provided, `position` is ignored.                                           |                     |       |
 
 
 #### ExifData
@@ -555,13 +639,14 @@ Represents EXIF data extracted from an image.
 
 Defines the options for capturing a picture.
 
-| Prop                | Type                                                    | Description                                                                               | Default             | Since |
-| ------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------- | ----- |
-| **`height`**        | <code>number</code>                                     | The desired height of the picture in pixels. If not provided, the device default is used. |                     |       |
-| **`width`**         | <code>number</code>                                     | The desired width of the picture in pixels. If not provided, the device default is used.  |                     |       |
-| **`quality`**       | <code>number</code>                                     | The quality of the captured image, from 0 to 100. Does not apply to `png` format.         | <code>85</code>     |       |
-| **`format`**        | <code><a href="#pictureformat">PictureFormat</a></code> | The format of the captured image.                                                         | <code>"jpeg"</code> |       |
-| **`saveToGallery`** | <code>boolean</code>                                    | If true, the captured image will be saved to the user's gallery.                          | <code>false</code>  | 7.5.0 |
+| Prop                   | Type                                                    | Description                                                                                                                                | Default             | Since |
+| ---------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ----- |
+| **`height`**           | <code>number</code>                                     | The desired height of the picture in pixels. If not provided, the device default is used.                                                  |                     |       |
+| **`width`**            | <code>number</code>                                     | The desired width of the picture in pixels. If not provided, the device default is used.                                                   |                     |       |
+| **`quality`**          | <code>number</code>                                     | The quality of the captured image, from 0 to 100. Does not apply to `png` format.                                                          | <code>85</code>     |       |
+| **`format`**           | <code><a href="#pictureformat">PictureFormat</a></code> | The format of the captured image.                                                                                                          | <code>"jpeg"</code> |       |
+| **`saveToGallery`**    | <code>boolean</code>                                    | If true, the captured image will be saved to the user's gallery.                                                                           | <code>false</code>  | 7.5.0 |
+| **`withExifLocation`** | <code>boolean</code>                                    | If true, the plugin will attempt to add GPS location data to the image's EXIF metadata. This may prompt the user for location permissions. | <code>false</code>  | 7.6.0 |
 
 
 #### CameraSampleOptions
@@ -646,6 +731,11 @@ Represents the detailed information of the currently active lens.
 ### Type Aliases
 
 
+#### GridMode
+
+<code>"none" | "3x3" | "4x4"</code>
+
+
 #### CameraPosition
 
 <code>"rear" | "front"</code>

package/android/build.gradle

@@ -49,7 +49,8 @@ dependencies {
     implementation project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     implementation 'androidx.exifinterface:exifinterface:1.4.1'
-    
+    implementation 'com.google.android.gms:play-services-location:21.3.0'
+
     // CameraX dependencies
     def camerax_version = "1.5.0-beta01"
     implementation "androidx.camera:camera-core:${camerax_version}"

package/android/src/main/AndroidManifest.xml

@@ -1,10 +1,7 @@
 
-  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-      >
+  <manifest xmlns:android="http://schemas.android.com/apk/res/android">
     <uses-permission android:name="android.permission.CAMERA" />
     <uses-permission android:name="android.permission.RECORD_AUDIO" />
-    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
     <uses-feature android:name="android.hardware.camera" />
     <uses-feature android:name="android.hardware.camera.autofocus" />
   </manifest>
-  

package/android/src/main/java/com/ahm/capacitor/camera/preview/CameraPreview.java

@@ -3,6 +3,7 @@ package com.ahm.capacitor.camera.preview;
 import static android.Manifest.permission.CAMERA;
 import static android.Manifest.permission.RECORD_AUDIO;
 
+import android.Manifest;
 import android.content.pm.ActivityInfo;
 import android.util.DisplayMetrics;
 import android.util.TypedValue;
@@ -23,8 +24,19 @@ import java.util.Objects;
 import android.util.Size;
 import android.util.Log;
 import com.ahm.capacitor.camera.preview.model.LensInfo;
-
+import com.google.android.gms.location.FusedLocationProviderClient;
+import com.google.android.gms.location.LocationServices;
 import org.json.JSONObject;
+import android.location.Location;
+import com.getcapacitor.Logger;
+
+interface CameraPreviewListener {
+  void onPictureTaken(String base64, JSONObject exif);
+  void onPictureTakenError(String message);
+  void onCameraStarted(int width, int height, int x, int y);
+  void onCameraStopped();
+  void onCaptureStarted();
+}
 
 @CapacitorPlugin(
   name = "CameraPreview",
@@ -37,20 +49,27 @@ import org.json.JSONObject;
       strings = { CAMERA },
       alias = CameraPreview.CAMERA_ONLY_PERMISSION_ALIAS
     ),
+    @Permission(
+      strings = { Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION },
+      alias = CameraPreview.CAMERA_WITH_LOCATION_PERMISSION_ALIAS
+    )
   }
 )
 public class CameraPreview
   extends Plugin
-  implements CameraXView.CameraXViewListener {
+  implements CameraPreviewListener {
 
   static final String CAMERA_WITH_AUDIO_PERMISSION_ALIAS = "cameraWithAudio";
   static final String CAMERA_ONLY_PERMISSION_ALIAS = "cameraOnly";
+  static final String CAMERA_WITH_LOCATION_PERMISSION_ALIAS = "cameraWithLocation";
 
   private String captureCallbackId = "";
   private String snapshotCallbackId = "";
   private String cameraStartCallbackId = "";
   private int previousOrientationRequest = ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED;
   private CameraXView cameraXView;
+  private FusedLocationProviderClient fusedLocationClient;
+  private Location lastLocation;
 
   @PluginMethod
   public void start(PluginCall call) {
@@ -87,12 +106,56 @@ public class CameraPreview
       return;
     }
 
+    final boolean withExifLocation = call.getBoolean("withExifLocation", false);
+
+    if (withExifLocation) {
+      if (getPermissionState(CAMERA_WITH_LOCATION_PERMISSION_ALIAS) != PermissionState.GRANTED) {
+        requestPermissionForAlias(CAMERA_WITH_LOCATION_PERMISSION_ALIAS, call, "captureWithLocationPermission");
+      } else {
+        getLocationAndCapture(call);
+      }
+    } else {
+      captureWithoutLocation(call);
+    }
+  }
+
+  @PermissionCallback
+  private void captureWithLocationPermission(PluginCall call) {
+    if (getPermissionState(CAMERA_WITH_LOCATION_PERMISSION_ALIAS) == PermissionState.GRANTED) {
+      getLocationAndCapture(call);
+    } else {
+      Logger.warn("Location permission denied. Capturing photo without location data.");
+      captureWithoutLocation(call);
+    }
+  }
+
+  private void getLocationAndCapture(PluginCall call) {
+      if (fusedLocationClient == null) {
+        fusedLocationClient = LocationServices.getFusedLocationProviderClient(getContext());
+      }
+        fusedLocationClient.getLastLocation().addOnSuccessListener(getActivity(), location -> {
+        lastLocation = location;
+        proceedWithCapture(call, lastLocation);
+      }).addOnFailureListener(e -> {
+        Logger.error("Failed to get location: " + e.getMessage());
+        proceedWithCapture(call, null);
+      });
+  }
+
+  private void captureWithoutLocation(PluginCall call) {
+    proceedWithCapture(call, null);
+  }
+
+  private void proceedWithCapture(PluginCall call, Location location) {
     bridge.saveCall(call);
     captureCallbackId = call.getCallbackId();
 
     Integer quality = Objects.requireNonNull(call.getInt("quality", 85));
-    final boolean saveToGallery = Boolean.TRUE.equals(call.getBoolean("saveToGallery", false));
-    cameraXView.capturePhoto(quality, saveToGallery);
+    final boolean saveToGallery = call.getBoolean("saveToGallery", false);
+    Integer width = call.getInt("width");
+    Integer height = call.getInt("height");
+
+    cameraXView.capturePhoto(quality, saveToGallery, width, height, location);
   }
 
   @PluginMethod
@@ -236,7 +299,7 @@ public class CameraPreview
     }
     rear.put("supportedPictureSizes", rearSizesJs);
     supportedPictureSizesResult.put(rear);
-    
+
     List<Size> frontSizes = CameraXView.getSupportedPictureSizes("front");
     JSObject front = new JSObject();
     front.put("facing", "front");
@@ -249,7 +312,7 @@ public class CameraPreview
     }
     front.put("supportedPictureSizes", frontSizesJs);
     supportedPictureSizesResult.put(front);
-    
+
     JSObject ret = new JSObject();
     ret.put("supportedPictureSizes", supportedPictureSizesResult);
     call.resolve(ret);
@@ -334,7 +397,9 @@ public class CameraPreview
     final boolean disableExifHeaderStripping = Boolean.TRUE.equals(call.getBoolean("disableExifHeaderStripping", false));
     final boolean lockOrientation = Boolean.TRUE.equals(call.getBoolean("lockAndroidOrientation", false));
     final boolean disableAudio = Boolean.TRUE.equals(call.getBoolean("disableAudio", true));
-    
+    final String aspectRatio = call.getString("aspectRatio", "fill");
+    final String gridMode = call.getString("gridMode", "none");
+
     float targetZoom = 1.0f;
     // Check if the selected device is a physical ultra-wide
     if (originalDeviceId != null) {
@@ -346,7 +411,7 @@ public class CameraPreview
                         Log.d("CameraPreview", "Ultra-wide lens selected. Targeting 0.5x zoom on logical camera.");
                         targetZoom = 0.5f;
                         // Force the use of the logical camera by clearing the specific deviceId
-                        deviceId = null; 
+                        deviceId = null;
                         break;
                     }
                 }
@@ -357,7 +422,7 @@ public class CameraPreview
 
     previousOrientationRequest = getBridge().getActivity().getRequestedOrientation();
     cameraXView = new CameraXView(getContext(), getBridge().getWebView());
-    cameraXView.setListener(this);
+    cameraXView.setListener((CameraXView.CameraXViewListener) this);
 
     String finalDeviceId = deviceId;
     float finalTargetZoom = targetZoom;
@@ -372,9 +437,9 @@ public class CameraPreview
         int computedHeight = height != 0 ? (int) TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, height, metrics) : getBridge().getWebView().getHeight();
         computedHeight -= (int) TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, paddingBottom, metrics);
 
-        CameraSessionConfiguration config = new CameraSessionConfiguration(finalDeviceId, position, computedX, computedY, computedWidth, computedHeight, paddingBottom, toBack, storeToFile, enableOpacity, enableZoom, disableExifHeaderStripping, disableAudio, 1.0f);
+        CameraSessionConfiguration config = new CameraSessionConfiguration(finalDeviceId, position, computedX, computedY, computedWidth, computedHeight, paddingBottom, toBack, storeToFile, enableOpacity, enableZoom, disableExifHeaderStripping, disableAudio, 1.0f, aspectRatio, gridMode);
         config.setTargetZoom(finalTargetZoom);
-        
+
         bridge.saveCall(call);
         cameraStartCallbackId = call.getCallbackId();
         cameraXView.startSession(config);
@@ -408,33 +473,50 @@ public class CameraPreview
   }
 
   @Override
-  public void onSampleTaken(String result) {
-    JSObject jsObject = new JSObject();
-    jsObject.put("value", result);
-    bridge.getSavedCall(snapshotCallbackId).resolve(jsObject);
+  public void onCaptureStarted() {
+    Log.i("CameraPreview", "Capture started");
   }
 
   @Override
-  public void onSampleTakenError(String message) {
-    bridge.getSavedCall(snapshotCallbackId).reject(message);
+  public void onCameraStarted(int width, int height, int x, int y) {
+    PluginCall call = bridge.getSavedCall(cameraStartCallbackId);
+    if (call != null) {
+        JSObject result = new JSObject();
+        result.put("width", width);
+        result.put("height", height);
+        result.put("x", x);
+        result.put("y", y);
+        call.resolve(result);
+        bridge.releaseCall(call);
+        cameraStartCallbackId = null; // Prevent re-use
+    }
   }
 
   @Override
-  public void onCameraStarted() {
-    PluginCall pluginCall = bridge.getSavedCall(cameraStartCallbackId);
-    if (pluginCall != null) {
-      pluginCall.resolve();
-      bridge.releaseCall(pluginCall);
-    }
+  public void onCameraStopped() {
+    // This method is no longer needed as onCameraStarted handles the promise resolution.
   }
 
-  @Override
-  public void onCameraStartError(String message) {
-    PluginCall pluginCall = bridge.getSavedCall(cameraStartCallbackId);
-    if (pluginCall != null) {
-      pluginCall.reject(message);
-      bridge.releaseCall(pluginCall);
+  @PluginMethod
+  public void setAspectRatio(PluginCall call) {
+    if (cameraXView == null || !cameraXView.isRunning()) {
+      call.reject("Camera is not running");
+      return;
     }
+    String aspectRatio = call.getString("aspectRatio", "fill");
+    cameraXView.setAspectRatio(aspectRatio);
+    call.resolve();
   }
 
+  @PluginMethod
+  public void getAspectRatio(PluginCall call) {
+    if (cameraXView == null || !cameraXView.isRunning()) {
+      call.reject("Camera is not running");
+      return;
+    }
+    String aspectRatio = cameraXView.getAspectRatio();
+    JSObject ret = new JSObject();
+    ret.put("aspectRatio", aspectRatio);
+    call.resolve(ret);
+  }
 }