Merge pull request #5 from CottaCush/readme_docs

Readme documentation, first pass

README.md

@@ -1,9 +1,119 @@
 # HiddenCamera
+
+##  \[ 🚧 Work in progress 🛠 👷🔧👷‍♀️️🔧️ 🚧 \]
+
 A library that allows you to capture images secretly, in background without alerting users.
 
 [![Build Status](https://travis-ci.org/CottaCush/HiddenCam.svg?branch=master)](https://travis-ci.org/CottaCush/HiddenCam)
-##
 
+## Gradle Dependency
+
+Add the dependency to your app's `build.gradle`:
+
+```groovy
+implementation 'com.cottacush:HiddenCamera:0.0.1'
+```
+
+## Usage
+`HiddenCam` uses `CameraX` under the hood. It is very easy to get started with Hidden cam. 
+First, initialize the camera engine with a `Context`, A `File` that 
+represents the base storage folder where the captured images will be saved to, 
+and an `OnImageCapturedListener` to get capture results:
+
+```kotlin
+val hiddenCam = HiddenCam(context, baseStorageFolder, captureListener)
+```
+Then prepare the camera for capturing by calling the `start()` method:
+
+```kotlin
+hiddenCam.start()
+```
+You can now start capturing images with:
+```kotlin
+hiddenCam.captureImage()
+```
+When you are no longer actively capturing images, stop the camera engine to free the camera hardware by calling:
+
+```kotlin
+hiddenCam.stop()
+```
+Finally, to clean up call
+
+```kotlin
+hiddenCam.destroy()
+```
+
+That's all for basic setup. The captured images should be save at the storage folder provided.
+
+## Customisation
+`HiddenCam` attempts to use some default values to improve ease of use.
+ Customization can be done by supplying additional arguments to the `HiddenCam()` constructor. 
+
+### Capture Mode (Reccuring or one shot)
+The capture mode is specified by the `CaptureTimeFrequency` class. 
+
+#### OneShot
+This capture mode should be used when you want to capture images manually with the `capture()` function. 
+It is the default setting for the `CaptureTimeFrequency` parameter
+
+```kotlin
+val hiddenCam = HiddenCam(context, baseStorageFolder, captureListener, captureFrequency = OneShot)
+```
+#### Recurring
+This capture mode should be used when you want to activate continuous captures at a specified interval. The captures will start as 
+soon as you call the the `start()` function on your `HiddenCam` instance. Manual calls to the `capture()` function will be ignored.
+
+```kotlin
+val hiddenCam = HiddenCam(context, baseStorageFolder, captureListener, captureFrequency = Recurring(captureIntervalMillis))
+```
+where captureIntervalMillis is the interval.
+
+### Resolution and Aspect Ratio
+You can either set `Resolution` or `AspectRatio`, not both.
+If `Resolution` is not set, `HiddenCam` will try to use the best resolution based on the 
+selected (or default) `AspectRatio` and phone's camera hardware capability. Resolution can manually be specified by passing a `Size` object to `HiddenCam` constructor. 
+For example, a resolution of 1080 X 1920 can be applied as follows:
+
+```kotlin
+val hiddenCam = HiddenCam(context, baseStorageFolder, captureListener, targetResolution = Size(1080, 1920))
+```
+To override the phone's default Aspect ratio, you can pass a `TargetAspectRatio` enum to the camera instance. For example, an aspect ratio 16:9 can be applied as follows:
+
+```kotlin
+val hiddenCam = HiddenCam(context, baseStorageFolder, captureListener, targetAspectRatio = TargetAspectRatio.RATIO_16_9)
+```
+
+### Rotation
+By default, the camera [rotation](https://developer.android.com/training/camerax/configuration#rotation) is set to match the default display's rotation during the creation of the `HiddenCam` object.
+This should work for most cases. If you need something more specific, you can set the rotation:
+```kotlin
+val rotation: Int = {...}
+val hiddenCam = HiddenCam(context, baseStorageFolder, captureListener, targetRotation = rotation)
+```
+
+### Camera Type
+You can use use the `CameraType` enum to specify weather you want to use a front camera, or a back camera. The default settings is  `FRONT_CAMERA`.
+For example, to use a back camera, you can do:
+```kotlin
+val hiddenCam = HiddenCam(context, baseStorageFolder, captureListener, cameraType = CameraType.BACK_CAMERA)
+```
+
+### Full Configuration
+Eventually, a fully customised `HiddenCam` instance would look like this: 
+
+```kotlin
+hiddenCam = HiddenCam(
+            context = context,
+            baseFileDirectory = baseStorageFolder,
+            imageCapturedListener = captureListener,
+            targetAspectRatio = TargetAspectRatio.RATIO_16_9,
+            targetResolution = Size(1920, 1080),
+            targetRotation = windowManager.defaultDisplay.rotation,
+            cameraType = CameraType.FRONT_CAMERA,
+            captureFrequency = Recurring(captureIntervalMillis = 15 * 1000)
+        )
+```
+
 ##  License
 
     Copyright (c) 2019 Cotta & Cush Limited.

dependencies.gradle

@@ -13,7 +13,7 @@ ext.versions = [
         kotlin            : '1.3.60-eap-25',
         ktx               : '1.0.2',
         androidx          : '1.0.2',
-        navigation          : '1.0.0',
+        navigation        : '1.0.0',
 
         cameraX           : '1.0.0-alpha06',
         androidxMaterial  : '1.0.0'

library/src/main/java/com/cottacush/android/hiddencam/CaptureTimerHandler.kt

@@ -25,7 +25,7 @@ internal class CaptureTimerHandler(
 
     companion object {
         private const val UPDATE_TIMER_COMMAND = 100
-        private const val INITIAL_CAPTURE_DELAY = 5 * 1000L
+        private const val INITIAL_CAPTURE_DELAY = 2 * 1000L
     }
 
     override fun handleMessage(msg: Message) {

library/src/main/java/com/cottacush/android/hiddencam/HiddenCam.kt

@@ -35,7 +35,7 @@ class HiddenCam(
     private lateinit var captureTimer: CaptureTimerHandler
     private val lifeCycleOwner = HiddenCamLifeCycleOwner()
 
-    //Preview UseCase
+    // Preview UseCase
     private var preview: Preview
     private var previewConfig = PreviewConfig.Builder().apply {
         setLensFacing(cameraType.lensFacing)
@@ -44,7 +44,7 @@ class HiddenCam(
         if (targetResolution != null) setTargetResolution(targetResolution)
     }.build()
 
-    //Image Capture Usecase
+    // Image Capture Usecase
     private var imageCapture: ImageCapture
     private var imageCaptureConfig: ImageCaptureConfig = ImageCaptureConfig.Builder()
         .apply {

sample/src/main/java/com/cottacush/android/hiddencam/oneshot/OneShotFragment.kt

@@ -24,9 +24,7 @@ import android.view.ViewGroup
 import android.widget.Toast
 import androidx.fragment.app.Fragment
 import com.cottacush.android.R
-import com.cottacush.android.hiddencam.HiddenCam
-import com.cottacush.android.hiddencam.MainActivity
-import com.cottacush.android.hiddencam.OnImageCapturedListener
+import com.cottacush.android.hiddencam.*
 import kotlinx.android.synthetic.main.fragment_oneshot.*
 import java.io.File
 
@@ -50,12 +48,14 @@ class OneShotFragment : Fragment(), OnImageCapturedListener {
         super.onViewCreated(view, savedInstanceState)
         mainActivity.setUpToolBar(getString(R.string.one_shot))
         baseStorageFolder = File(mainActivity.getExternalFilesDir(null), "HiddenCam").apply {
-            if (!exists()) mkdir()
+            if (exists()) deleteRecursively()
+            mkdir()
         }
         hiddenCam = HiddenCam(
             mainActivity, baseStorageFolder, this,
-            targetResolution = Size(1080, 1920)
+            targetResolution = Size(1920, 1080)
         )
+
         captureButton.setOnClickListener {
             hiddenCam.captureImage()
         }

sample/src/main/java/com/cottacush/android/hiddencam/recurring/RecurringFragment.kt

@@ -51,9 +51,11 @@ class RecurringFragment : Fragment(), OnImageCapturedListener {
         super.onViewCreated(view, savedInstanceState)
         mainActivity.setUpToolBar(getString(R.string.recurring))
         baseStorageFolder = File(mainActivity.getExternalFilesDir(null), "HiddenCam").apply {
-            if (!exists()) mkdir()
+            if (exists()) deleteRecursively()
+            mkdir()
         }
-        hiddenCam = HiddenCam(mainActivity, baseStorageFolder, this,
+        hiddenCam = HiddenCam(
+            mainActivity, baseStorageFolder, this,
             CaptureTimeFrequency.Recurring(RECURRING_INTERVAL),
             targetResolution = Size(1080, 1920)
         )