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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +218 -35
  2. package/android/.gradle/8.14.2/checksums/checksums.lock +0 -0
  3. package/android/.gradle/8.14.2/checksums/md5-checksums.bin +0 -0
  4. package/android/.gradle/8.14.2/checksums/sha1-checksums.bin +0 -0
  5. package/android/.gradle/8.14.2/executionHistory/executionHistory.bin +0 -0
  6. package/android/.gradle/8.14.2/executionHistory/executionHistory.lock +0 -0
  7. package/android/.gradle/8.14.2/fileHashes/fileHashes.bin +0 -0
  8. package/android/.gradle/8.14.2/fileHashes/fileHashes.lock +0 -0
  9. package/android/.gradle/8.14.2/fileHashes/resourceHashesCache.bin +0 -0
  10. package/android/.gradle/buildOutputCleanup/buildOutputCleanup.lock +0 -0
  11. package/android/.gradle/file-system.probe +0 -0
  12. package/android/build.gradle +3 -1
  13. package/android/src/main/AndroidManifest.xml +1 -4
  14. package/android/src/main/java/com/ahm/capacitor/camera/preview/CameraPreview.java +759 -83
  15. package/android/src/main/java/com/ahm/capacitor/camera/preview/CameraXView.java +2813 -805
  16. package/android/src/main/java/com/ahm/capacitor/camera/preview/GridOverlayView.java +112 -0
  17. package/android/src/main/java/com/ahm/capacitor/camera/preview/model/CameraDevice.java +55 -46
  18. package/android/src/main/java/com/ahm/capacitor/camera/preview/model/CameraLens.java +61 -52
  19. package/android/src/main/java/com/ahm/capacitor/camera/preview/model/CameraSessionConfiguration.java +161 -59
  20. package/android/src/main/java/com/ahm/capacitor/camera/preview/model/LensInfo.java +29 -23
  21. package/android/src/main/java/com/ahm/capacitor/camera/preview/model/ZoomFactors.java +24 -23
  22. package/dist/docs.json +333 -29
  23. package/dist/esm/definitions.d.ts +156 -13
  24. package/dist/esm/definitions.js.map +1 -1
  25. package/dist/esm/web.d.ts +52 -3
  26. package/dist/esm/web.js +592 -95
  27. package/dist/esm/web.js.map +1 -1
  28. package/dist/plugin.cjs.js +590 -95
  29. package/dist/plugin.cjs.js.map +1 -1
  30. package/dist/plugin.js +590 -95
  31. package/dist/plugin.js.map +1 -1
  32. package/ios/Sources/CapgoCameraPreview/CameraController.swift +907 -222
  33. package/ios/Sources/CapgoCameraPreview/GridOverlayView.swift +65 -0
  34. package/ios/Sources/CapgoCameraPreview/Plugin.swift +986 -250
  35. package/package.json +2 -2
package/README.md CHANGED
@@ -92,6 +92,52 @@ Then run
92
92
  npx cap sync
93
93
  ```
94
94
 
95
+ ## Optional Configuration
96
+
97
+ To use certain features of this plugin, you will need to add the following permissions/keys to your native project configurations.
98
+
99
+ ### Android
100
+
101
+ In your `android/app/src/main/AndroidManifest.xml`:
102
+
103
+ - **Audio Recording** (`disableAudio: false`):
104
+ ```xml
105
+ <uses-permission android:name="android.permission.RECORD_AUDIO" />
106
+ ```
107
+
108
+ - **Saving to Gallery** (`saveToGallery: true`):
109
+ ```xml
110
+ <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
111
+ ```
112
+
113
+ - **Location in EXIF Data** (`withExifLocation: true`):
114
+ ```xml
115
+ <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
116
+ <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
117
+ ```
118
+
119
+ ### iOS
120
+
121
+ 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.
122
+
123
+ - **Audio Recording** (`disableAudio: false`):
124
+ ```xml
125
+ <key>NSMicrophoneUsageDescription</key>
126
+ <string>To record audio with videos</string>
127
+ ```
128
+
129
+ - **Saving to Gallery** (`saveToGallery: true`):
130
+ ```xml
131
+ <key>NSPhotoLibraryUsageDescription</key>
132
+ <string>To save photos to your gallery</string>
133
+ ```
134
+
135
+ - **Location in EXIF Data** (`withExifLocation: true`):
136
+ ```xml
137
+ <key>NSLocationWhenInUseUsageDescription</key>
138
+ <string>To add location data to your photos</string>
139
+ ```
140
+
95
141
  ## Extra Android installation steps
96
142
 
97
143
  **Important** `camera-preview` 3+ requires Gradle 7.
@@ -174,6 +220,10 @@ Documentation for the [uploader](https://github.com/Cap-go/capacitor-uploader)
174
220
  * [`capture(...)`](#capture)
175
221
  * [`captureSample(...)`](#capturesample)
176
222
  * [`getSupportedFlashModes()`](#getsupportedflashmodes)
223
+ * [`setAspectRatio(...)`](#setaspectratio)
224
+ * [`getAspectRatio()`](#getaspectratio)
225
+ * [`setGridMode(...)`](#setgridmode)
226
+ * [`getGridMode()`](#getgridmode)
177
227
  * [`getHorizontalFov()`](#gethorizontalfov)
178
228
  * [`getSupportedPictureSizes()`](#getsupportedpicturesizes)
179
229
  * [`setFlashMode(...)`](#setflashmode)
@@ -189,6 +239,9 @@ Documentation for the [uploader](https://github.com/Cap-go/capacitor-uploader)
189
239
  * [`removeAllListeners()`](#removealllisteners)
190
240
  * [`setDeviceId(...)`](#setdeviceid)
191
241
  * [`getDeviceId()`](#getdeviceid)
242
+ * [`getPreviewSize()`](#getpreviewsize)
243
+ * [`setPreviewSize(...)`](#setpreviewsize)
244
+ * [`setFocus(...)`](#setfocus)
192
245
  * [Interfaces](#interfaces)
193
246
  * [Type Aliases](#type-aliases)
194
247
  * [Enums](#enums)
@@ -203,7 +256,7 @@ The main interface for the CameraPreview plugin.
203
256
  ### start(...)
204
257
 
205
258
  ```typescript
206
- start(options: CameraPreviewOptions) => Promise<void>
259
+ start(options: CameraPreviewOptions) => Promise<{ width: number; height: number; x: number; y: number; }>
207
260
  ```
208
261
 
209
262
  Starts the camera preview.
@@ -212,6 +265,8 @@ Starts the camera preview.
212
265
  | ------------- | --------------------------------------------------------------------- | ------------------------------------------- |
213
266
  | **`options`** | <code><a href="#camerapreviewoptions">CameraPreviewOptions</a></code> | - The configuration for the camera preview. |
214
267
 
268
+ **Returns:** <code>Promise&lt;{ width: number; height: number; x: number; y: number; }&gt;</code>
269
+
215
270
  **Since:** 0.0.1
216
271
 
217
272
  --------------------
@@ -283,6 +338,72 @@ Gets the flash modes supported by the active camera.
283
338
  --------------------
284
339
 
285
340
 
341
+ ### setAspectRatio(...)
342
+
343
+ ```typescript
344
+ setAspectRatio(options: { aspectRatio: "4:3" | "16:9"; x?: number; y?: number; }) => Promise<{ width: number; height: number; x: number; y: number; }>
345
+ ```
346
+
347
+ Set the aspect ratio of the camera preview.
348
+
349
+ | Param | Type | Description |
350
+ | ------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
351
+ | **`options`** | <code>{ aspectRatio: '4:3' \| '16:9'; x?: number; y?: number; }</code> | - 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. |
352
+
353
+ **Returns:** <code>Promise&lt;{ width: number; height: number; x: number; y: number; }&gt;</code>
354
+
355
+ **Since:** 7.4.0
356
+
357
+ --------------------
358
+
359
+
360
+ ### getAspectRatio()
361
+
362
+ ```typescript
363
+ getAspectRatio() => Promise<{ aspectRatio: "4:3" | "16:9"; }>
364
+ ```
365
+
366
+ Gets the current aspect ratio of the camera preview.
367
+
368
+ **Returns:** <code>Promise&lt;{ aspectRatio: '4:3' | '16:9'; }&gt;</code>
369
+
370
+ **Since:** 7.4.0
371
+
372
+ --------------------
373
+
374
+
375
+ ### setGridMode(...)
376
+
377
+ ```typescript
378
+ setGridMode(options: { gridMode: GridMode; }) => Promise<void>
379
+ ```
380
+
381
+ Sets the grid mode of the camera preview overlay.
382
+
383
+ | Param | Type | Description |
384
+ | ------------- | ------------------------------------------------------------ | -------------------------------------------------- |
385
+ | **`options`** | <code>{ gridMode: <a href="#gridmode">GridMode</a>; }</code> | - The desired grid mode ('none', '3x3', or '4x4'). |
386
+
387
+ **Since:** 8.0.0
388
+
389
+ --------------------
390
+
391
+
392
+ ### getGridMode()
393
+
394
+ ```typescript
395
+ getGridMode() => Promise<{ gridMode: GridMode; }>
396
+ ```
397
+
398
+ Gets the current grid mode of the camera preview overlay.
399
+
400
+ **Returns:** <code>Promise&lt;{ gridMode: <a href="#gridmode">GridMode</a>; }&gt;</code>
401
+
402
+ **Since:** 8.0.0
403
+
404
+ --------------------
405
+
406
+
286
407
  ### getHorizontalFov()
287
408
 
288
409
  ```typescript
@@ -441,14 +562,14 @@ Gets the current zoom state, including min/max and current lens info.
441
562
  ### setZoom(...)
442
563
 
443
564
  ```typescript
444
- setZoom(options: { level: number; ramp?: boolean; }) => Promise<void>
565
+ setZoom(options: { level: number; ramp?: boolean; autoFocus?: boolean; }) => Promise<void>
445
566
  ```
446
567
 
447
- Sets the camera's zoom level.
568
+ Sets the zoom level of the camera.
448
569
 
449
- | Param | Type | Description |
450
- | ------------- | ----------------------------------------------- | ----------------------------------------------------- |
451
- | **`options`** | <code>{ level: number; ramp?: boolean; }</code> | - The desired zoom level. `ramp` is currently unused. |
570
+ | Param | Type | Description |
571
+ | ------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
572
+ | **`options`** | <code>{ level: number; ramp?: boolean; autoFocus?: boolean; }</code> | - The desired zoom level. `ramp` is currently unused. `autoFocus` defaults to true. |
452
573
 
453
574
  **Since:** 7.4.0
454
575
 
@@ -515,6 +636,53 @@ Gets the ID of the currently active camera device.
515
636
  --------------------
516
637
 
517
638
 
639
+ ### getPreviewSize()
640
+
641
+ ```typescript
642
+ getPreviewSize() => Promise<{ x: number; y: number; width: number; height: number; }>
643
+ ```
644
+
645
+ Gets the current preview size and position.
646
+
647
+ **Returns:** <code>Promise&lt;{ x: number; y: number; width: number; height: number; }&gt;</code>
648
+
649
+ --------------------
650
+
651
+
652
+ ### setPreviewSize(...)
653
+
654
+ ```typescript
655
+ setPreviewSize(options: { x?: number; y?: number; width: number; height: number; }) => Promise<{ width: number; height: number; x: number; y: number; }>
656
+ ```
657
+
658
+ Sets the preview size and position.
659
+
660
+ | Param | Type | Description |
661
+ | ------------- | ----------------------------------------------------------------------- | -------------------------------- |
662
+ | **`options`** | <code>{ x?: number; y?: number; width: number; height: number; }</code> | The new position and dimensions. |
663
+
664
+ **Returns:** <code>Promise&lt;{ width: number; height: number; x: number; y: number; }&gt;</code>
665
+
666
+ --------------------
667
+
668
+
669
+ ### setFocus(...)
670
+
671
+ ```typescript
672
+ setFocus(options: { x: number; y: number; }) => Promise<void>
673
+ ```
674
+
675
+ Sets the camera focus to a specific point in the preview.
676
+
677
+ | Param | Type | Description |
678
+ | ------------- | -------------------------------------- | -------------------- |
679
+ | **`options`** | <code>{ x: number; y: number; }</code> | - The focus options. |
680
+
681
+ **Since:** 8.1.0
682
+
683
+ --------------------
684
+
685
+
518
686
  ### Interfaces
519
687
 
520
688
 
@@ -522,28 +690,31 @@ Gets the ID of the currently active camera device.
522
690
 
523
691
  Defines the configuration options for starting the camera preview.
524
692
 
525
- | Prop | Type | Description | Default |
526
- | ---------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------- |
527
- | **`parent`** | <code>string</code> | The parent element to attach the video preview to. | |
528
- | **`className`** | <code>string</code> | A CSS class name to add to the preview element. | |
529
- | **`width`** | <code>number</code> | The width of the preview in pixels. Defaults to the screen width. | |
530
- | **`height`** | <code>number</code> | The height of the preview in pixels. Defaults to the screen height. | |
531
- | **`x`** | <code>number</code> | The horizontal origin of the preview, in pixels. | |
532
- | **`y`** | <code>number</code> | The vertical origin of the preview, in pixels. | |
533
- | **`includeSafeAreaInsets`** | <code>boolean</code> | Adjusts the y-position to account for safe areas (e.g., notches). | <code>false</code> |
534
- | **`toBack`** | <code>boolean</code> | If true, places the preview behind the webview. | <code>true</code> |
535
- | **`paddingBottom`** | <code>number</code> | Bottom padding for the preview, in pixels. | |
536
- | **`rotateWhenOrientationChanged`** | <code>boolean</code> | Whether to rotate the preview when the device orientation changes. | <code>true</code> |
537
- | **`position`** | <code>string</code> | The camera to use. | <code>"rear"</code> |
538
- | **`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> |
539
- | **`disableExifHeaderStripping`** | <code>boolean</code> | If true, prevents the plugin from rotating the image based on EXIF data. | <code>false</code> |
540
- | **`enableHighResolution`** | <code>boolean</code> | If true, enables high-resolution image capture. | <code>false</code> |
541
- | **`disableAudio`** | <code>boolean</code> | If true, disables the audio stream, preventing audio permission requests. | <code>false</code> |
542
- | **`lockAndroidOrientation`** | <code>boolean</code> | If true, locks the device orientation while the camera is active. | <code>false</code> |
543
- | **`enableOpacity`** | <code>boolean</code> | If true, allows the camera preview's opacity to be changed. | <code>false</code> |
544
- | **`enableZoom`** | <code>boolean</code> | If true, enables pinch-to-zoom functionality on the preview. | <code>false</code> |
545
- | **`enableVideoMode`** | <code>boolean</code> | If true, uses the video-optimized preset for the camera session. | <code>false</code> |
546
- | **`deviceId`** | <code>string</code> | The `deviceId` of the camera to use. If provided, `position` is ignored. | |
693
+ | Prop | Type | Description | Default | Since |
694
+ | ---------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----- |
695
+ | **`parent`** | <code>string</code> | The parent element to attach the video preview to. | | |
696
+ | **`className`** | <code>string</code> | A CSS class name to add to the preview element. | | |
697
+ | **`width`** | <code>number</code> | The width of the preview in pixels. Defaults to the screen width. | | |
698
+ | **`height`** | <code>number</code> | The height of the preview in pixels. Defaults to the screen height. | | |
699
+ | **`x`** | <code>number</code> | The horizontal origin of the preview, in pixels. | | |
700
+ | **`y`** | <code>number</code> | The vertical origin of the preview, in pixels. | | |
701
+ | **`aspectRatio`** | <code>'4:3' \| '16:9'</code> | 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. | | 2.0.0 |
702
+ | **`gridMode`** | <code><a href="#gridmode">GridMode</a></code> | The grid overlay to display on the camera preview. | <code>"none"</code> | 2.1.0 |
703
+ | **`includeSafeAreaInsets`** | <code>boolean</code> | Adjusts the y-position to account for safe areas (e.g., notches). | <code>false</code> | |
704
+ | **`toBack`** | <code>boolean</code> | If true, places the preview behind the webview. | <code>true</code> | |
705
+ | **`paddingBottom`** | <code>number</code> | Bottom padding for the preview, in pixels. | | |
706
+ | **`rotateWhenOrientationChanged`** | <code>boolean</code> | Whether to rotate the preview when the device orientation changes. | <code>true</code> | |
707
+ | **`position`** | <code>string</code> | The camera to use. | <code>"rear"</code> | |
708
+ | **`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> | |
709
+ | **`disableExifHeaderStripping`** | <code>boolean</code> | If true, prevents the plugin from rotating the image based on EXIF data. | <code>false</code> | |
710
+ | **`disableAudio`** | <code>boolean</code> | If true, disables the audio stream, preventing audio permission requests. | <code>true</code> | |
711
+ | **`lockAndroidOrientation`** | <code>boolean</code> | If true, locks the device orientation while the camera is active. | <code>false</code> | |
712
+ | **`enableOpacity`** | <code>boolean</code> | If true, allows the camera preview's opacity to be changed. | <code>false</code> | |
713
+ | **`enableZoom`** | <code>boolean</code> | If true, enables pinch-to-zoom functionality on the preview. | <code>false</code> | |
714
+ | **`enableVideoMode`** | <code>boolean</code> | If true, uses the video-optimized preset for the camera session. | <code>false</code> | |
715
+ | **`deviceId`** | <code>string</code> | The `deviceId` of the camera to use. If provided, `position` is ignored. | | |
716
+ | **`initialZoomLevel`** | <code>number</code> | The initial zoom level when starting the camera preview. If the requested zoom level is not available, the native plugin will reject. | <code>1.0</code> | 2.2.0 |
717
+ | **`positioning`** | <code><a href="#camerapositioning">CameraPositioning</a></code> | The vertical positioning of the camera preview. | <code>"center"</code> | 2.3.0 |
547
718
 
548
719
 
549
720
  #### ExifData
@@ -555,13 +726,15 @@ Represents EXIF data extracted from an image.
555
726
 
556
727
  Defines the options for capturing a picture.
557
728
 
558
- | Prop | Type | Description | Default | Since |
559
- | ------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------- | ----- |
560
- | **`height`** | <code>number</code> | The desired height of the picture in pixels. If not provided, the device default is used. | | |
561
- | **`width`** | <code>number</code> | The desired width of the picture in pixels. If not provided, the device default is used. | | |
562
- | **`quality`** | <code>number</code> | The quality of the captured image, from 0 to 100. Does not apply to `png` format. | <code>85</code> | |
563
- | **`format`** | <code><a href="#pictureformat">PictureFormat</a></code> | The format of the captured image. | <code>"jpeg"</code> | |
564
- | **`saveToGallery`** | <code>boolean</code> | If true, the captured image will be saved to the user's gallery. | <code>false</code> | 7.5.0 |
729
+ | Prop | Type | Description | Default | Since |
730
+ | ---------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ----- |
731
+ | **`height`** | <code>number</code> | | | |
732
+ | **`width`** | <code>number</code> | | | |
733
+ | **`aspectRatio`** | <code>string</code> | | | 7.7.0 |
734
+ | **`quality`** | <code>number</code> | The quality of the captured image, from 0 to 100. Does not apply to `png` format. | <code>85</code> | |
735
+ | **`format`** | <code><a href="#pictureformat">PictureFormat</a></code> | The format of the captured image. | <code>"jpeg"</code> | |
736
+ | **`saveToGallery`** | <code>boolean</code> | If true, the captured image will be saved to the user's gallery. | <code>false</code> | 7.5.0 |
737
+ | **`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 |
565
738
 
566
739
 
567
740
  #### CameraSampleOptions
@@ -646,11 +819,21 @@ Represents the detailed information of the currently active lens.
646
819
  ### Type Aliases
647
820
 
648
821
 
822
+ #### GridMode
823
+
824
+ <code>"none" | "3x3" | "4x4"</code>
825
+
826
+
649
827
  #### CameraPosition
650
828
 
651
829
  <code>"rear" | "front"</code>
652
830
 
653
831
 
832
+ #### CameraPositioning
833
+
834
+ <code>"center" | "top" | "bottom"</code>
835
+
836
+
654
837
  #### PictureFormat
655
838
 
656
839
  <code>"jpeg" | "png"</code>
Binary file
@@ -49,7 +49,9 @@ dependencies {
49
49
  implementation project(':capacitor-android')
50
50
  implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
51
51
  implementation 'androidx.exifinterface:exifinterface:1.4.1'
52
-
52
+ implementation 'com.google.android.gms:play-services-location:21.3.0'
53
+ implementation 'androidx.coordinatorlayout:coordinatorlayout:1.3.0'
54
+
53
55
  // CameraX dependencies
54
56
  def camerax_version = "1.5.0-beta01"
55
57
  implementation "androidx.camera:camera-core:${camerax_version}"
@@ -1,10 +1,7 @@
1
1
 
2
- <manifest xmlns:android="http://schemas.android.com/apk/res/android"
3
- >
2
+ <manifest xmlns:android="http://schemas.android.com/apk/res/android">
4
3
  <uses-permission android:name="android.permission.CAMERA" />
5
4
  <uses-permission android:name="android.permission.RECORD_AUDIO" />
6
- <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
7
5
  <uses-feature android:name="android.hardware.camera" />
8
6
  <uses-feature android:name="android.hardware.camera.autofocus" />
9
7
  </manifest>
10
-