@capgo/camera-preview 7.4.0-beta.1 → 7.4.0-beta.10

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

@@ -0,0 +1,82 @@
+package com.ahm.capacitor.camera.preview;
+
+import android.content.Context;
+import android.graphics.Canvas;
+import android.graphics.Paint;
+import android.util.AttributeSet;
+import android.view.View;
+
+public class GridOverlayView extends View {
+    private Paint gridPaint;
+    private String gridMode = "none";
+
+    public GridOverlayView(Context context) {
+        super(context);
+        init();
+    }
+
+    public GridOverlayView(Context context, AttributeSet attrs) {
+        super(context, attrs);
+        init();
+    }
+
+    public GridOverlayView(Context context, AttributeSet attrs, int defStyleAttr) {
+        super(context, attrs, defStyleAttr);
+        init();
+    }
+
+    private void init() {
+        gridPaint = new Paint();
+        gridPaint.setColor(0x80FFFFFF); // Semi-transparent white
+        gridPaint.setStrokeWidth(2f);
+        gridPaint.setStyle(Paint.Style.STROKE);
+        gridPaint.setAntiAlias(true);
+    }
+
+    public void setGridMode(String mode) {
+        String previousMode = this.gridMode;
+        this.gridMode = mode != null ? mode : "none";
+        setVisibility("none".equals(this.gridMode) ? View.GONE : View.VISIBLE);
+        android.util.Log.d("GridOverlayView", "setGridMode: Changed from '" + previousMode + "' to '" + this.gridMode + "', visibility: " + ("none".equals(this.gridMode) ? "GONE" : "VISIBLE"));
+        invalidate();
+    }
+
+    @Override
+    protected void onDraw(Canvas canvas) {
+        super.onDraw(canvas);
+
+        if ("none".equals(gridMode)) {
+            return;
+        }
+
+        int width = getWidth();
+        int height = getHeight();
+
+        if (width <= 0 || height <= 0) {
+            return;
+        }
+
+        if ("3x3".equals(gridMode)) {
+            drawGrid(canvas, width, height, 3);
+        } else if ("4x4".equals(gridMode)) {
+            drawGrid(canvas, width, height, 4);
+        }
+    }
+
+    private void drawGrid(Canvas canvas, int width, int height, int divisions) {
+        float stepX = (float) width / divisions;
+        float stepY = (float) height / divisions;
+
+        // Draw vertical lines
+        for (int i = 1; i < divisions; i++) {
+            float x = i * stepX;
+            canvas.drawLine(x, 0, x, height, gridPaint);
+        }
+
+        // Draw horizontal lines
+        for (int i = 1; i < divisions; i++) {
+            float y = i * stepY;
+            canvas.drawLine(0, y, width, y, gridPaint);
+        }
+    }
+}

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

@@ -18,12 +18,14 @@ public class CameraSessionConfiguration {
     private final boolean disableExifHeaderStripping;
     private final boolean disableAudio;
     private final float zoomFactor;
+    private final String aspectRatio;
+    private final String gridMode;
     private float targetZoom = 1.0f;
 
-    public CameraSessionConfiguration(String deviceId, String position, int x, int y, int width, int height, 
-                                    int paddingBottom, boolean toBack, boolean storeToFile, boolean enableOpacity, 
-                                    boolean enableZoom, boolean disableExifHeaderStripping, boolean disableAudio, 
-                                    float zoomFactor) {
+    public CameraSessionConfiguration(String deviceId, String position, int x, int y, int width, int height,
+                                    int paddingBottom, boolean toBack, boolean storeToFile, boolean enableOpacity,
+                                    boolean enableZoom, boolean disableExifHeaderStripping, boolean disableAudio,
+                                    float zoomFactor, String aspectRatio, String gridMode) {
         this.deviceId = deviceId;
         this.position = position;
         this.x = x;
@@ -38,6 +40,8 @@ public class CameraSessionConfiguration {
         this.disableExifHeaderStripping = disableExifHeaderStripping;
         this.disableAudio = disableAudio;
         this.zoomFactor = zoomFactor;
+        this.aspectRatio = aspectRatio;
+        this.gridMode = gridMode != null ? gridMode : "none";
     }
 
     public void setTargetZoom(float zoom) {
@@ -62,4 +66,14 @@ public class CameraSessionConfiguration {
     public boolean isDisableExifHeaderStripping() { return disableExifHeaderStripping; }
     public boolean isDisableAudio() { return disableAudio; }
     public float getZoomFactor() { return zoomFactor; }
-} 
+    public String getAspectRatio() { return aspectRatio; }
+    public String getGridMode() { return gridMode; }
+
+    // Additional getters with "get" prefix for compatibility
+    public boolean getToBack() { return toBack; }
+    public boolean getStoreToFile() { return storeToFile; }
+    public boolean getEnableOpacity() { return enableOpacity; }
+    public boolean getEnableZoom() { return enableZoom; }
+    public boolean getDisableExifHeaderStripping() { return disableExifHeaderStripping; }
+    public boolean getDisableAudio() { return disableAudio; }
+}

package/dist/docs.json

@@ -7,7 +7,7 @@
     "methods": [
       {
         "name": "start",
-        "signature": "(options: CameraPreviewOptions) => Promise<void>",
+        "signature": "(options: CameraPreviewOptions) => Promise<{ width: number; height: number; x: number; y: number; }>",
         "parameters": [
           {
             "name": "options",
@@ -15,7 +15,7 @@
             "type": "CameraPreviewOptions"
           }
         ],
-        "returns": "Promise<void>",
+        "returns": "Promise<{ width: number; height: number; x: number; y: number; }>",
         "tags": [
           {
             "name": "param",
@@ -23,7 +23,7 @@
           },
           {
             "name": "returns",
-            "text": "A promise that resolves when the camera preview is started."
+            "text": "A promise that resolves with the preview dimensions."
           },
           {
             "name": "since",
@@ -57,7 +57,7 @@
       },
       {
         "name": "capture",
-        "signature": "(options: CameraPreviewPictureOptions) => Promise<{ value: string; }>",
+        "signature": "(options: CameraPreviewPictureOptions) => Promise<{ value: string; exif: ExifData; }>",
         "parameters": [
           {
             "name": "options",
@@ -65,7 +65,7 @@
             "type": "CameraPreviewPictureOptions"
           }
         ],
-        "returns": "Promise<{ value: string; }>",
+        "returns": "Promise<{ value: string; exif: ExifData; }>",
         "tags": [
           {
             "name": "param",
@@ -82,6 +82,7 @@
         ],
         "docs": "Captures a picture from the camera.",
         "complexTypes": [
+          "ExifData",
           "CameraPreviewPictureOptions"
         ],
         "slug": "capture"
@@ -138,6 +139,106 @@
         ],
         "slug": "getsupportedflashmodes"
       },
+      {
+        "name": "setAspectRatio",
+        "signature": "(options: { aspectRatio: '4:3' | '16:9'; x?: number; y?: number; }) => Promise<{ width: number; height: number; x: number; y: number; }>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "- The desired aspect ratio and optional position.\n- aspectRatio: The desired aspect ratio ('4:3' or '16:9')\n- x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.\n- y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically.",
+            "type": "{ aspectRatio: '4:3' | '16:9'; x?: number | undefined; y?: number | undefined; }"
+          }
+        ],
+        "returns": "Promise<{ width: number; height: number; x: number; y: number; }>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options - The desired aspect ratio and optional position.\n- aspectRatio: The desired aspect ratio ('4:3' or '16:9')\n- x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.\n- y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically."
+          },
+          {
+            "name": "returns",
+            "text": "A promise that resolves with the actual preview dimensions and position."
+          },
+          {
+            "name": "since",
+            "text": "7.4.0"
+          }
+        ],
+        "docs": "Set the aspect ratio of the camera preview.",
+        "complexTypes": [],
+        "slug": "setaspectratio"
+      },
+      {
+        "name": "getAspectRatio",
+        "signature": "() => Promise<{ aspectRatio: '4:3' | '16:9'; }>",
+        "parameters": [],
+        "returns": "Promise<{ aspectRatio: '4:3' | '16:9'; }>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "A promise that resolves with the current aspect ratio."
+          },
+          {
+            "name": "since",
+            "text": "7.4.0"
+          }
+        ],
+        "docs": "Gets the current aspect ratio of the camera preview.",
+        "complexTypes": [],
+        "slug": "getaspectratio"
+      },
+      {
+        "name": "setGridMode",
+        "signature": "(options: { gridMode: GridMode; }) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "- The desired grid mode ('none', '3x3', or '4x4').",
+            "type": "{ gridMode: GridMode; }"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options - The desired grid mode ('none', '3x3', or '4x4')."
+          },
+          {
+            "name": "returns",
+            "text": "A promise that resolves when the grid mode is set."
+          },
+          {
+            "name": "since",
+            "text": "8.0.0"
+          }
+        ],
+        "docs": "Sets the grid mode of the camera preview overlay.",
+        "complexTypes": [
+          "GridMode"
+        ],
+        "slug": "setgridmode"
+      },
+      {
+        "name": "getGridMode",
+        "signature": "() => Promise<{ gridMode: GridMode; }>",
+        "parameters": [],
+        "returns": "Promise<{ gridMode: GridMode; }>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "A promise that resolves with the current grid mode."
+          },
+          {
+            "name": "since",
+            "text": "8.0.0"
+          }
+        ],
+        "docs": "Gets the current grid mode of the camera preview overlay.",
+        "complexTypes": [
+          "GridMode"
+        ],
+        "slug": "getgridmode"
+      },
       {
         "name": "getHorizontalFov",
         "signature": "() => Promise<{ result: number; }>",
@@ -482,6 +583,45 @@
         "docs": "Gets the ID of the currently active camera device.",
         "complexTypes": [],
         "slug": "getdeviceid"
+      },
+      {
+        "name": "getPreviewSize",
+        "signature": "() => Promise<{ x: number; y: number; width: number; height: number; }>",
+        "parameters": [],
+        "returns": "Promise<{ x: number; y: number; width: number; height: number; }>",
+        "tags": [
+          {
+            "name": "returns"
+          }
+        ],
+        "docs": "Gets the current preview size and position.",
+        "complexTypes": [],
+        "slug": "getpreviewsize"
+      },
+      {
+        "name": "setPreviewSize",
+        "signature": "(options: { x: number; y: number; width: number; height: number; }) => Promise<{ width: number; height: number; x: number; y: number; }>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "The new position and dimensions.",
+            "type": "{ x: number; y: number; width: number; height: number; }"
+          }
+        ],
+        "returns": "Promise<{ width: number; height: number; x: number; y: number; }>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options The new position and dimensions."
+          },
+          {
+            "name": "returns",
+            "text": "A promise that resolves with the actual preview dimensions and position."
+          }
+        ],
+        "docs": "Sets the preview size and position.",
+        "complexTypes": [],
+        "slug": "setpreviewsize"
       }
     ],
     "properties": []
@@ -566,6 +706,36 @@
           "complexTypes": [],
           "type": "number | undefined"
         },
+        {
+          "name": "aspectRatio",
+          "tags": [
+            {
+              "text": "2.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The aspect ratio of the camera preview, '4:3' or '16:9' or 'fill'.\nCannot be set if width or height is provided, otherwise the call will be rejected.\nUse setPreviewSize to adjust size after starting.",
+          "complexTypes": [],
+          "type": "'4:3' | '16:9' | 'fill' | undefined"
+        },
+        {
+          "name": "gridMode",
+          "tags": [
+            {
+              "text": "\"none\"",
+              "name": "default"
+            },
+            {
+              "text": "2.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The grid overlay to display on the camera preview.",
+          "complexTypes": [
+            "GridMode"
+          ],
+          "type": "GridMode"
+        },
         {
           "name": "includeSafeAreaInsets",
           "tags": [
@@ -688,7 +858,7 @@
           "name": "disableAudio",
           "tags": [
             {
-              "text": "false",
+              "text": "true",
               "name": "default"
             }
           ],
@@ -774,6 +944,14 @@
         }
       ]
     },
+    {
+      "name": "ExifData",
+      "slug": "exifdata",
+      "docs": "Represents EXIF data extracted from an image.",
+      "tags": [],
+      "methods": [],
+      "properties": []
+    },
     {
       "name": "CameraPreviewPictureOptions",
       "slug": "camerapreviewpictureoptions",
@@ -820,6 +998,38 @@
             "PictureFormat"
           ],
           "type": "PictureFormat"
+        },
+        {
+          "name": "saveToGallery",
+          "tags": [
+            {
+              "text": "false",
+              "name": "default"
+            },
+            {
+              "text": "7.5.0",
+              "name": "since"
+            }
+          ],
+          "docs": "If true, the captured image will be saved to the user's gallery.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
+        {
+          "name": "withExifLocation",
+          "tags": [
+            {
+              "text": "false",
+              "name": "default"
+            },
+            {
+              "text": "7.6.0",
+              "name": "since"
+            }
+          ],
+          "docs": "If true, the plugin will attempt to add GPS location data to the image's EXIF metadata.\nThis may prompt the user for location permissions.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
         }
       ]
     },
@@ -1119,6 +1329,25 @@
     }
   ],
   "typeAliases": [
+    {
+      "name": "GridMode",
+      "slug": "gridmode",
+      "docs": "",
+      "types": [
+        {
+          "text": "\"none\"",
+          "complexTypes": []
+        },
+        {
+          "text": "\"3x3\"",
+          "complexTypes": []
+        },
+        {
+          "text": "\"4x4\"",
+          "complexTypes": []
+        }
+      ]
+    },
     {
       "name": "CameraPosition",
       "slug": "cameraposition",

package/dist/esm/definitions.d.ts

@@ -1,5 +1,6 @@
 export type CameraPosition = "rear" | "front";
 export type FlashMode = CameraPreviewFlashMode;
+export type GridMode = "none" | "3x3" | "4x4";
 export declare enum DeviceType {
     ULTRA_WIDE = "ultraWide",
     WIDE_ANGLE = "wideAngle",
@@ -92,6 +93,20 @@ export interface CameraPreviewOptions {
      * @platform android, ios
      */
     y?: number;
+    /**
+     * The aspect ratio of the camera preview, '4:3' or '16:9' or 'fill'.
+     * Cannot be set if width or height is provided, otherwise the call will be rejected.
+     * Use setPreviewSize to adjust size after starting.
+     *
+     * @since 2.0.0
+     */
+    aspectRatio?: '4:3' | '16:9' | 'fill';
+    /**
+     * The grid overlay to display on the camera preview.
+     * @default "none"
+     * @since 2.1.0
+     */
+    gridMode?: GridMode;
     /**
      * Adjusts the y-position to account for safe areas (e.g., notches).
      * @platform ios
@@ -140,7 +155,7 @@ export interface CameraPreviewOptions {
     enableHighResolution?: boolean;
     /**
      * If true, disables the audio stream, preventing audio permission requests.
-     * @default false
+     * @default true
      */
     disableAudio?: boolean;
     /**
@@ -192,6 +207,23 @@ export interface CameraPreviewPictureOptions {
      * @default "jpeg"
      */
     format?: PictureFormat;
+    /**
+     * If true, the captured image will be saved to the user's gallery.
+     * @default false
+     * @since 7.5.0
+     */
+    saveToGallery?: boolean;
+    /**
+     * 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.
+     * @default false
+     * @since 7.6.0
+     */
+    withExifLocation?: boolean;
+}
+/** Represents EXIF data extracted from an image. */
+export interface ExifData {
+    [key: string]: any;
 }
 export type PictureFormat = "jpeg" | "png";
 /** Defines a standard picture size with width and height. */
@@ -241,10 +273,19 @@ export interface CameraPreviewPlugin {
      * Starts the camera preview.
      *
      * @param {CameraPreviewOptions} options - The configuration for the camera preview.
-     * @returns {Promise<void>} A promise that resolves when the camera preview is started.
+     * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the preview dimensions.
      * @since 0.0.1
      */
-    start(options: CameraPreviewOptions): Promise<void>;
+    start(options: CameraPreviewOptions): Promise<{
+        /** The width of the preview in pixels. */
+        width: number;
+        /** The height of the preview in pixels. */
+        height: number;
+        /** The horizontal origin of the preview, in pixels. */
+        x: number;
+        /** The vertical origin of the preview, in pixels. */
+        y: number;
+    }>;
     /**
      * Stops the camera preview.
      *
@@ -262,6 +303,7 @@ export interface CameraPreviewPlugin {
      */
     capture(options: CameraPreviewPictureOptions): Promise<{
         value: string;
+        exif: ExifData;
     }>;
     /**
      * Captures a single frame from the camera preview stream.
@@ -282,6 +324,54 @@ export interface CameraPreviewPlugin {
     getSupportedFlashModes(): Promise<{
         result: CameraPreviewFlashMode[];
     }>;
+    /**
+     * Set the aspect ratio of the camera preview.
+     *
+     * @param {{ aspectRatio: '4:3' | '16:9'; x?: number; y?: number }} options - The desired aspect ratio and optional position.
+     *   - aspectRatio: The desired aspect ratio ('4:3' or '16:9')
+     *   - x: Optional x coordinate for positioning. If not provided, view will be auto-centered horizontally.
+     *   - y: Optional y coordinate for positioning. If not provided, view will be auto-centered vertically.
+     * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.
+     * @since 7.4.0
+     */
+    setAspectRatio(options: {
+        aspectRatio: '4:3' | '16:9';
+        x?: number;
+        y?: number;
+    }): Promise<{
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Gets the current aspect ratio of the camera preview.
+     *
+     * @returns {Promise<{ aspectRatio: '4:3' | '16:9' }>} A promise that resolves with the current aspect ratio.
+     * @since 7.4.0
+     */
+    getAspectRatio(): Promise<{
+        aspectRatio: '4:3' | '16:9';
+    }>;
+    /**
+     * Sets the grid mode of the camera preview overlay.
+     *
+     * @param {{ gridMode: GridMode }} options - The desired grid mode ('none', '3x3', or '4x4').
+     * @returns {Promise<void>} A promise that resolves when the grid mode is set.
+     * @since 8.0.0
+     */
+    setGridMode(options: {
+        gridMode: GridMode;
+    }): Promise<void>;
+    /**
+     * Gets the current grid mode of the camera preview overlay.
+     *
+     * @returns {Promise<{ gridMode: GridMode }>} A promise that resolves with the current grid mode.
+     * @since 8.0.0
+     */
+    getGridMode(): Promise<{
+        gridMode: GridMode;
+    }>;
     /**
      * Gets the horizontal field of view (FoV) for the active camera.
      * Note: This can be an estimate on some devices.
@@ -418,4 +508,30 @@ export interface CameraPreviewPlugin {
     getDeviceId(): Promise<{
         deviceId: string;
     }>;
+    /**
+     * Gets the current preview size and position.
+     * @returns {Promise<{x: number, y: number, width: number, height: number}>}
+     */
+    getPreviewSize(): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /**
+     * Sets the preview size and position.
+     * @param options The new position and dimensions.
+     * @returns {Promise<{ width: number; height: number; x: number; y: number }>} A promise that resolves with the actual preview dimensions and position.
+     */
+    setPreviewSize(options: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Promise<{
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    }>;
 }