Skip to content

Commit 5457e07

Browse files
Pranav0-0AggarwalPranav0-0Aggarwal
authored
Merge pull request #39 from bassamadnan/main
add documentation using mkdocs-material
2 parents 886fc52 + b197a05 commit 5457e07

21 files changed

+1136
-0
lines changed

‎.github/workflows/ci.yml

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# name: ci
2+
# on:
3+
# push:
4+
# branches:
5+
# - main
6+
# permissions:
7+
# contents: write
8+
# jobs:
9+
# deploy:
10+
# runs-on: ubuntu-latest
11+
# steps:
12+
# - uses: actions/checkout@v4
13+
# - name: Configure Git Credentials
14+
# run: |
15+
# git config user.name github-actions[bot]
16+
# git config user.email 41898282+github-actions[bot]@users.noreply.github.com
17+
# - uses: actions/setup-python@v5
18+
# with:
19+
# python-version: 3.x
20+
# - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
21+
# - uses: actions/cache@v4
22+
# with:
23+
# key: mkdocs-material-${{ env.cache_id }}
24+
# path: .cache
25+
# restore-keys: |
26+
# mkdocs-material-
27+
# - run: pip install mkdocs-material
28+
# - run: mkdocs gh-deploy --force

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,4 @@ dist-ssr
2525
videos_cache.txt
2626
images_cache.txt
2727
videos_cache.txt
28+
venv/

‎docs/assets/PictoPy-logo.png

563 KB
Loading

‎docs/backend/api.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# API
2+
3+
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.
4+
Follow this [Link](https://www.postman.com/cryosat-explorer-62744145/workspace/pictopy/overview) to get example request and response.
5+
## Table of Contents
6+
1. [Albums](#albums)
7+
2. [Image](#image)
8+
3. [Face Recognition and Tagging](#face-recognition-and-tagging)
9+
10+
## Albums
11+
12+
We briefly discuss the endpoints related to albums, all of these fall under the `/albums` route
13+
14+
### Create Album
15+
- **Endpoint**: `POST /albums/create-album`
16+
- **Description**: Creates a new album with the given name and optional description.
17+
- **Request Format**:
18+
```json
19+
{
20+
"name": "string",
21+
"description": "string" (optional)
22+
}
23+
```
24+
- **Response**: Message confirming album creation.
25+
26+
### Delete Album
27+
- **Endpoint**: `DELETE /albums/delete-album`
28+
- **Description**: Deletes an existing album by name.
29+
- **Request Format**:
30+
```json
31+
{
32+
"name": "string"
33+
}
34+
```
35+
- **Response**: Message confirming album deletion.
36+
37+
### Add Multiple Images to Album
38+
- **Endpoint**: `POST /albums/add-multiple-to-album`
39+
- **Description**: Adds multiple images to an existing album.
40+
- **Request Format**:
41+
```json
42+
{
43+
"album_name": "string",
44+
"paths": ["string", "string", ...]
45+
}
46+
```
47+
- **Response**: Message confirming images were added to the album.
48+
49+
### Remove Image from Album
50+
- **Endpoint**: `DELETE /albums/remove-from-album`
51+
- **Description**: Removes a single image from an album.
52+
- **Request Format**:
53+
```json
54+
{
55+
"album_name": "string",
56+
"path": "string"
57+
}
58+
```
59+
- **Response**: Message confirming image removal from the album.
60+
61+
### View Album Photos
62+
- **Endpoint**: `GET /albums/view-album`
63+
- **Description**: Retrieves all photos in a specified album.
64+
- **Query Parameters**: `album_name` (string)
65+
- **Response**: JSON object containing album name and list of photos.
66+
67+
### Edit Album Description
68+
- **Endpoint**: `PUT /albums/edit-album-description`
69+
- **Description**: Updates the description of an existing album.
70+
- **Request Format**:
71+
```json
72+
{
73+
"name": "string",
74+
"description": "string"
75+
}
76+
```
77+
- **Response**: Message confirming album description update.
78+
79+
### View All Albums
80+
- **Endpoint**: `GET /albums/view-all`
81+
- **Description**: Retrieves a list of all albums.
82+
- **Response**: JSON object containing a list of all albums.
83+
84+
## Image
85+
We briefly discuss the endpoints related to images, all of these fall under the `/images` route
86+
### Get All Images
87+
- **Endpoint**: `GET /images/all-images`
88+
- **Description**: Retrieves a list of all image files in the system.
89+
- **Response**: JSON object containing a list of image file paths.
90+
91+
### Add Multiple Images
92+
- **Endpoint**: `POST /images/images`
93+
- **Description**: Adds multiple images to the system and processes them in the background.
94+
- **Request Format**:
95+
```json
96+
{
97+
"paths": ["string", "string", ...]
98+
}
99+
```
100+
- **Response**: Message indicating that images are being processed.
101+
102+
### Delete Image
103+
- **Endpoint**: `DELETE /images/delete-image`
104+
- **Description**: Deletes a single image from the system.
105+
- **Request Format**:
106+
```json
107+
{
108+
"path": "string"
109+
}
110+
```
111+
- **Response**: Message confirming image deletion.
112+
113+
### Get All Image Objects
114+
- **Endpoint**: `GET /images/all-image-objects`
115+
- **Description**: Retrieves all images and their associated object classes.
116+
- **Response**: JSON object mapping image paths to their object classes.
117+
118+
### Get Class IDs
119+
- **Endpoint**: `GET /images/class-ids`
120+
- **Description**: Retrieves the object classes for a specific image.
121+
- **Query Parameters**: `path` (string) - full path to the image
122+
- **Response**: JSON object containing the classes detected in the image.
123+
124+
### Add Folder
125+
- **Endpoint**: `POST /images/add-folder`
126+
- **Description**: Adds all images from a specified folder to the system and processes them in the background.
127+
- **Request Format**:
128+
```json
129+
{
130+
"folder_path": "string"
131+
}
132+
```
133+
- **Response**: Message indicating the number of images being processed from the folder.
134+
135+
## Face Recognition and Tagging
136+
We briefly discuss the endpoints related to face tagging and recognition, all of these fall under the `/tag` route
137+
### Face Matching
138+
- **Endpoint**: `GET /tag/match`
139+
- **Description**: Finds similar faces across all images in the database.
140+
- **Response**: JSON object containing pairs of similar images and their similarity scores.
141+
142+
### Face Clusters
143+
- **Endpoint**: `GET /tag/clusters`
144+
- **Description**: Retrieves clusters of similar faces across all images.
145+
- **Response**: JSON object containing clusters of images with similar faces.
146+
147+
### Related Images
148+
- **Endpoint**: `GET /tag/related-images`
149+
- **Description**: Finds images with faces related to the face in the given image.
150+
- **Query Parameters**: `path` (string) - full path to the image
151+
- **Response**: JSON object containing a list of related image paths.

‎docs/backend/database.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Database

‎docs/backend/directory-structure.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Directory Structure
2+
3+
The entry point for the backend is in `main.py`, which initializes the databases and handles the startup and shutdown for the FastAPI server.
4+
5+
The code for the application mainly lies in the `app/` directory the heirarchy of which looks like this:
6+
7+
```bash
8+
.
9+
├── main.py
10+
└── app/
11+
├── config/
12+
├── database/
13+
├── facecluster/
14+
├── facenet/
15+
├── models/
16+
├── routes/
17+
├── utils/
18+
└── yolov8/
19+
20+
```
21+
22+
We will discuss what each of these directories do and the relevant files they contain
23+
24+
## config
25+
26+
Related to variables used accross the application.
27+
28+
| Name | Description |
29+
|-------------|-------------|
30+
| `settings.py` | Contains configuration files for the application, mainly paths and parameters which are used across the application |
31+
32+
33+
## database
34+
35+
This directory contains files related to database operations, including table creation, query handeling and some helper functions on the tables.
36+
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
37+
created.
38+
39+
| Name | Description |
40+
|----------------|-------------|
41+
| `albums.py` | Handles operations related to photo albums, including creating, deleting, and managing albums and their contents. |
42+
| `faces.py` | Manages face-related data, including storing and retrieving face embeddings for facial recognition. |
43+
| `images.py` | Deals with image-related operations, such as storing image metadata, managing image IDs, and handling image classifications. |
44+
| `yolo_mapping.py`| Creates and manages mappings for YOLO object detection classes. |
45+
46+
47+
## facecluster
48+
This directory contains files related to face clustering functionality, which is used to group similar faces together across different images.
49+
50+
| Name | Description |
51+
|----------------------|-------------|
52+
| `init_face_cluster.py` | Initializes and manages the face clustering system |
53+
| `facecluster.py` | Implements the FaceCluster class, which handles the core face clustering logic |
54+
55+
56+
## facenet
57+
This directory contains files related to facial recognition functionality using FaceNet, a deep learning model for face embedding.
58+
59+
| Name | Description |
60+
|------|-------------|
61+
| `facenet.py` | Implements face detection and embedding generation using FaceNet and YOLOv8 |
62+
| `preprocess.py` | Contains utility functions for image preprocessing and embedding manipulation |
63+
64+
65+
## models
66+
This directory contains pre-trained machine learning models used in the application.
67+
68+
| Name | Description |
69+
|------|-------------|
70+
| `facenet.onnx` | Pre-trained FaceNet model for generating face embeddings |
71+
| `yolov8n-face.onnx` | YOLOv8 model trained specifically for face detection |
72+
| `yolov8n.onnx` | YOLOv8 model for general object detection |
73+
74+
## routes
75+
This directory contains API route definitions for different functionalities of the application.
76+
77+
| Name | Description |
78+
|------|-------------|
79+
| `albums.py` | Handles API routes for album-related operations (create, delete, add/remove photos, view albums) |
80+
| `facetagging.py` | Manages routes for face matching, clustering, and finding related images |
81+
| `images.py` | Deals with image-related operations (adding, deleting, retrieving images and their metadata) |
82+
83+
84+
85+
## utils
86+
This directory contains utility functions and helper modules used across the application.
87+
88+
| Name | Description |
89+
|------|-------------|
90+
| `classification.py` | Provides functions for image classification using YOLOv8 |
91+
| `metadata.py` | Extracts and processes metadata from image files |
92+
| `path_id_mapping.py` | Handles mappings between image paths and their database IDs |
93+
| `wrappers.py` | Contains decorator functions for validating album and image existence |
94+
95+
96+
97+
## yolov8
98+
This directory contains implementations and utilities for the YOLOv8 object detection model.
99+
The code is taken from [This Repositry](https://github.com/ibaiGorordo/ONNX-YOLOv8-Object-Detection)
100+
101+
| Name | Description |
102+
|------|-------------|
103+
| `utils.py` | Provides utility functions for YOLOv8, including NMS, IoU computation, and drawing detections |
104+
| `YOLOv8.py` | Implements the YOLOv8 class for object detection, including model initialization, inference, and post-processing |

‎docs/backend/image-processing.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Image Processing

‎docs/backend/setup.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Backend Setup
2+
3+
4+
## Setup Directory
5+
!!! note "Base Directory"
6+
All commands executed below are with respect to the `backend/` directory
7+
8+
### Installing requirments
9+
10+
We suggest setting up a virtual environment and run the following command
11+
```bash
12+
pip install -r requirements.txt
13+
```
14+
15+
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
16+
`.bat` and `.sh` formats.
17+
18+
!!! note "UNIX Development"
19+
For UNIX based systems, to run in development mode run
20+
```bash
21+
./run.sh --test
22+
```
23+
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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Gallery View

‎docs/frontend/setup.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Frontend Setup

0 commit comments

Comments
 (0)