Merge pull request #39 from bassamadnan/main

add documentation using mkdocs-material

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+# name: ci
+# on:
+#   push:
+#     branches:
+#       - main
+# permissions:
+#   contents: write
+# jobs:
+#   deploy:
+#     runs-on: ubuntu-latest
+#     steps:
+#       - uses: actions/checkout@v4
+#       - name: Configure Git Credentials
+#         run: |
+#           git config user.name github-actions[bot]
+#           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+#       - uses: actions/setup-python@v5
+#         with:
+#           python-version: 3.x
+#       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+#       - uses: actions/cache@v4
+#         with:
+#           key: mkdocs-material-${{ env.cache_id }}
+#           path: .cache
+#           restore-keys: |
+#             mkdocs-material-
+#       - run: pip install mkdocs-material
+#       - run: mkdocs gh-deploy --force

.gitignore

@@ -25,3 +25,4 @@ dist-ssr
 videos_cache.txt
 images_cache.txt
 videos_cache.txt
+venv/

docs/backend/api.md

@@ -0,0 +1,151 @@
+# API
+
+The API calls to PictoPy are done via HTTP requests since we are hosting our backend on a Flask server. This was done to ensure low coupling between the frontend and the backend.
+Follow this [Link](https://www.postman.com/cryosat-explorer-62744145/workspace/pictopy/overview) to get example request and response.
+## Table of Contents
+1. [Albums](#albums)
+2. [Image](#image)
+3. [Face Recognition and Tagging](#face-recognition-and-tagging)
+
+## Albums
+
+We briefly discuss the endpoints related to albums, all of these fall under the `/albums` route
+
+### Create Album
+- **Endpoint**: `POST /albums/create-album`
+- **Description**: Creates a new album with the given name and optional description.
+- **Request Format**:
+  ```json
+  {
+    "name": "string",
+    "description": "string" (optional)
+  }
+  ```
+- **Response**: Message confirming album creation.
+
+### Delete Album
+- **Endpoint**: `DELETE /albums/delete-album`
+- **Description**: Deletes an existing album by name.
+- **Request Format**:
+  ```json
+  {
+    "name": "string"
+  }
+  ```
+- **Response**: Message confirming album deletion.
+
+### Add Multiple Images to Album
+- **Endpoint**: `POST /albums/add-multiple-to-album`
+- **Description**: Adds multiple images to an existing album.
+- **Request Format**:
+  ```json
+  {
+    "album_name": "string",
+    "paths": ["string", "string", ...]
+  }
+  ```
+- **Response**: Message confirming images were added to the album.
+
+### Remove Image from Album
+- **Endpoint**: `DELETE /albums/remove-from-album`
+- **Description**: Removes a single image from an album.
+- **Request Format**:
+  ```json
+  {
+    "album_name": "string",
+    "path": "string"
+  }
+  ```
+- **Response**: Message confirming image removal from the album.
+
+### View Album Photos
+- **Endpoint**: `GET /albums/view-album`
+- **Description**: Retrieves all photos in a specified album.
+- **Query Parameters**: `album_name` (string)
+- **Response**: JSON object containing album name and list of photos.
+
+### Edit Album Description
+- **Endpoint**: `PUT /albums/edit-album-description`
+- **Description**: Updates the description of an existing album.
+- **Request Format**:
+  ```json
+  {
+    "name": "string",
+    "description": "string"
+  }
+  ```
+- **Response**: Message confirming album description update.
+
+### View All Albums
+- **Endpoint**: `GET /albums/view-all`
+- **Description**: Retrieves a list of all albums.
+- **Response**: JSON object containing a list of all albums.
+
+## Image
+We briefly discuss the endpoints related to images, all of these fall under the `/images` route
+### Get All Images
+- **Endpoint**: `GET /images/all-images`
+- **Description**: Retrieves a list of all image files in the system.
+- **Response**: JSON object containing a list of image file paths.
+
+### Add Multiple Images
+- **Endpoint**: `POST /images/images`
+- **Description**: Adds multiple images to the system and processes them in the background.
+- **Request Format**:
+  ```json
+  {
+    "paths": ["string", "string", ...]
+  }
+  ```
+- **Response**: Message indicating that images are being processed.
+
+### Delete Image
+- **Endpoint**: `DELETE /images/delete-image`
+- **Description**: Deletes a single image from the system.
+- **Request Format**:
+  ```json
+  {
+    "path": "string"
+  }
+  ```
+- **Response**: Message confirming image deletion.
+
+### Get All Image Objects
+- **Endpoint**: `GET /images/all-image-objects`
+- **Description**: Retrieves all images and their associated object classes.
+- **Response**: JSON object mapping image paths to their object classes.
+
+### Get Class IDs
+- **Endpoint**: `GET /images/class-ids`
+- **Description**: Retrieves the object classes for a specific image.
+- **Query Parameters**: `path` (string) - full path to the image
+- **Response**: JSON object containing the classes detected in the image.
+
+### Add Folder
+- **Endpoint**: `POST /images/add-folder`
+- **Description**: Adds all images from a specified folder to the system and processes them in the background.
+- **Request Format**:
+  ```json
+  {
+    "folder_path": "string"
+  }
+  ```
+- **Response**: Message indicating the number of images being processed from the folder.
+
+## Face Recognition and Tagging
+We briefly discuss the endpoints related to face tagging and recognition, all of these fall under the `/tag` route
+### Face Matching
+- **Endpoint**: `GET /tag/match`
+- **Description**: Finds similar faces across all images in the database.
+- **Response**: JSON object containing pairs of similar images and their similarity scores.
+
+### Face Clusters
+- **Endpoint**: `GET /tag/clusters`
+- **Description**: Retrieves clusters of similar faces across all images.
+- **Response**: JSON object containing clusters of images with similar faces.
+
+### Related Images
+- **Endpoint**: `GET /tag/related-images`
+- **Description**: Finds images with faces related to the face in the given image.
+- **Query Parameters**: `path` (string) - full path to the image
+- **Response**: JSON object containing a list of related image paths.

docs/backend/database.md

@@ -0,0 +1 @@
+# Database

docs/backend/directory-structure.md

@@ -0,0 +1,104 @@
+# Directory Structure
+
+The entry point for the backend is in `main.py`, which initializes the databases and handles the startup and shutdown for the FastAPI server.
+
+The code for the application mainly lies in the `app/` directory the heirarchy of which looks like this:
+
+```bash
+.
+├── main.py
+└── app/
+    ├── config/
+    ├── database/
+    ├── facecluster/
+    ├── facenet/
+    ├── models/
+    ├── routes/
+    ├── utils/
+    └── yolov8/
+
+```
+
+We will discuss what each of these directories do and the relevant files they contain
+
+## config
+
+Related to variables used accross the application.
+
+| Name   | Description |
+|-------------|-------------|
+| `settings.py`     | Contains configuration files for the application, mainly paths and parameters which are used across the application |
+
+
+## database
+
+This directory contains files related to database operations, including table creation, query handeling and some helper functions on the tables.
+These files are the places where most of the SQL queries are written. By default, on startup this directory is where the databases (`.db` files) is
+created.
+
+| Name           | Description |
+|----------------|-------------|
+| `albums.py`     | Handles operations related to photo albums, including creating, deleting, and managing albums and their contents. |
+| `faces.py`     | Manages face-related data, including storing and retrieving face embeddings for facial recognition. |
+| `images.py`      | Deals with image-related operations, such as storing image metadata, managing image IDs, and handling image classifications. |
+| `yolo_mapping.py`| Creates and manages mappings for YOLO object detection classes. |
+
+
+## facecluster
+This directory contains files related to face clustering functionality, which is used to group similar faces together across different images.
+
+| Name                 | Description |
+|----------------------|-------------|
+| `init_face_cluster.py` | Initializes and manages the face clustering system |
+| `facecluster.py`       | Implements the FaceCluster class, which handles the core face clustering logic |
+
+
+## facenet
+This directory contains files related to facial recognition functionality using FaceNet, a deep learning model for face embedding.
+
+| Name | Description |
+|------|-------------|
+| `facenet.py` | Implements face detection and embedding generation using FaceNet and YOLOv8 |
+| `preprocess.py` | Contains utility functions for image preprocessing and embedding manipulation |
+
+
+## models
+This directory contains pre-trained machine learning models used in the application.
+
+| Name | Description |
+|------|-------------|
+| `facenet.onnx` | Pre-trained FaceNet model for generating face embeddings |
+| `yolov8n-face.onnx` | YOLOv8 model trained specifically for face detection |
+| `yolov8n.onnx` | YOLOv8 model for general object detection |
+
+## routes
+This directory contains API route definitions for different functionalities of the application.
+
+| Name | Description |
+|------|-------------|
+| `albums.py` | Handles API routes for album-related operations (create, delete, add/remove photos, view albums) |
+| `facetagging.py` | Manages routes for face matching, clustering, and finding related images |
+| `images.py` | Deals with image-related operations (adding, deleting, retrieving images and their metadata) |
+
+
+
+## utils
+This directory contains utility functions and helper modules used across the application.
+
+| Name | Description |
+|------|-------------|
+| `classification.py` | Provides functions for image classification using YOLOv8 |
+| `metadata.py` | Extracts and processes metadata from image files |
+| `path_id_mapping.py` | Handles mappings between image paths and their database IDs |
+| `wrappers.py` | Contains decorator functions for validating album and image existence |
+
+
+
+## yolov8
+This directory contains implementations and utilities for the YOLOv8 object detection model.
+The code is taken from [This Repositry](https://github.com/ibaiGorordo/ONNX-YOLOv8-Object-Detection)
+
+| Name | Description |
+|------|-------------|
+| `utils.py` | Provides utility functions for YOLOv8, including NMS, IoU computation, and drawing detections |
+| `YOLOv8.py` | Implements the YOLOv8 class for object detection, including model initialization, inference, and post-processing |

docs/backend/image-processing.md

@@ -0,0 +1 @@
+# Image Processing

docs/backend/setup.md

@@ -0,0 +1,23 @@
+# Backend Setup
+
+
+## Setup Directory
+!!! note "Base Directory"
+    All commands executed below are with respect to the `backend/` directory
+
+### Installing requirments
+
+We suggest setting up a virtual environment and run the following command
+```bash
+pip install -r requirements.txt
+```
+
+The entry point for backend is `main.py` , since PictoPy is built on top of FastAPI, we suggest using the `run` scripts which are available in both
+`.bat` and `.sh` formats.
+
+!!! note "UNIX Development"
+    For UNIX based systems, to run in development mode run
+    ```bash
+    ./run.sh --test
+    ```
+The backend should now be successfully running on port 8000 by default. To change this modify the start-up scripts.

docs/frontend/gallery-view.md

@@ -0,0 +1 @@
+# Gallery View

docs/frontend/setup.md

@@ -0,0 +1 @@
+# Frontend Setup

docs/frontend/state-management.md

@@ -0,0 +1 @@
+# State Management

docs/frontend/ui-components.md

@@ -0,0 +1 @@
+# UI Components