Merge pull request #16 from rileydrizzy/main

Merge

.gitignore

@@ -117,9 +117,8 @@ yb2audio/data/*/*
 #yb2audio/development
 
 # Development Enviroment
-dev.py
-dev_env.txt
 **/development/
+dev.py
 
 # Keys
 set_environment_variables.sh

CONTRIBUTE.MD

@@ -0,0 +1,54 @@
+# Welcome Contributors
+
+Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+We're excited you're interested in contributing to this project! This guide outlines the process for submitting code contributions and provides some helpful tips for getting started.
+
+## Getting Started
+
+Before diving in, here are a few things to keep in mind:
+
+* **Issue Tracking:** We use GitHub issues to track bugs, feature requests, and other project tasks. Before working on a contribution, it's recommended to check the existing issues list and see if there's something you'd like to tackle. This helps avoid duplicate efforts and ensures your contribution aligns with project priorities.
+
+* **Development Setup:**  We recommend following the project's setup instructions to configure your development environment. This ensures you have the necessary tools and dependencies to work on the project.
+
+## Making a Contribution
+
+Here's a general workflow for contributing code:
+
+1. **Fork the Repository:**  Click the "Fork" button on the project's main page on GitHub. This creates a copy of the repository in your own account, allowing you to make changes without affecting the original project.
+
+2. **Clone Your Fork:**  Use Git to clone your forked repository to your local machine. This creates a local working directory where you can make changes.
+
+3. **Create a Branch:**  Create a new branch for your specific contribution. This helps keep your changes isolated from the main codebase. Use a descriptive branch name that reflects the nature of your contribution (e.g., "fix-login-bug" or "add-new-feature").
+
+    EXAMPLE --> (`git checkout -b feature/AmazingFeature`)
+
+4. **Make Your Changes:**  Edit the relevant files and make your code changes.
+
+5. **Test Changes**: Make your changes and ensure that the code passes all tests.
+
+6. **Commit Your Changes:**  Use Git to commit your changes with clear and concise commit messages. Each commit message should describe what you changed and why.
+
+    EXAMPLE --> (`git commit -m 'Add some AmazingFeature'`)
+
+7. **Push Your Changes:**  Push your commits to your forked repository on GitHub.
+
+8. **Create a Pull Request:**  On GitHub, navigate to your forked repository and create a pull request. This sends a notification to the project maintainers about your proposed changes.
+9. **Address Feedback:**  Project maintainers may review your pull request and provide feedback or request changes. Be responsive to feedback and make any necessary adjustments.
+
+## Contribution Guidelines
+
+* **Code Style:**  Follow the project's existing coding style guidelines (e.g., indentation, naming conventions) to ensure consistency.
+
+* **Testing:**  Whenever possible, include unit tests for your code changes. This helps ensure the functionality you added or modified works as expected and doesn't introduce regressions.
+
+* **Documentation:**  If your contribution adds new features or modifies existing functionality, consider updating the project's documentation to reflect the changes.
+
+## Additional Information
+
+* **License:**  Be sure to understand the project's license before contributing. This clarifies how your code can be used and distributed.
+
+* **Community:**  Feel free to reach out to the project maintainers (if available) if you have any questions or need help with your contribution.
+
+We appreciate your contributions! By following these guidelines, you can help us make this project even better.

README.md

@@ -12,7 +12,7 @@
 <br />
 <div align="center">
   <a href="https://github.com/AISaturdaysLagos/Cohort8-Ransome-Kuti-Ladipo">
-    <img src="images/logo.png" alt="Logo" width="80" height="80">
+    <img src=".assets/logo.png" alt="Logo" width="80" height="80">
   </a>
 
 <h3 align="center">NSL-2-AUDIO</h3>
@@ -31,33 +31,25 @@
   </p>
 </div>
 
+> [!IMPORTANT]  
+> This project is currently in a very early development/experimental stage. There are a lot of unimplemented/broken features at the moment. Contributions are welcome to help out with the progress!
+
 <!-- TABLE OF CONTENTS -->
-<details>
-  <summary>Table of Contents</summary>
-  <ol>
-    <li>
-      <a href="#about-the-project">About The Project</a>
-      <ul>
-        <li><a href="#built-with">Built With</a></li>
-      </ul>
-    </li>
-    <li>
-      <a href="#getting-started">Getting Started</a>
-      <ul>
-        <li><a href="#prerequisites">Prerequisites</a></li>
-      </ul>
-    </li>
-    <li><a href="#usage">Usage</a></li>
-    <li><a href="#roadmap">Roadmap</a></li>
-    <li><a href="#contributing">Contributing</a></li>
-    <li><a href="#license">License</a></li>
-    <li><a href="#contact">Contact</a></li>
-    <li><a href="#acknowledgments">Acknowledgments</a></li>
-  </ol>
-</details>
+## Table of Contents
+
+- [About](#about)
+- [Demos](#demos)
+- [System Architecture](#system-architecture)
+- [Quick Start](#quick-start)
+- [Getting Started](#getting-started)
+- [Roadmap](#bulb-roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+- [Contact](#contact)
+- [Acknowledgments](#acknowledgments)
 
 <!-- ABOUT THE PROJECT -->
-## About The Project
+## About
 
 ***Overview:*** \
 This project is dedicated to the development of an Automatic Sign Language Translation system, with a specific focus on translating Nigerian Sign Language (NSL) into one of the Low-Resource Languages (LRLs) spoken in Nigeria. The primary objective is to address the communication challenges faced by the NSL community and contribute to inclusivity and employment opportunities in education and the workforce.
@@ -79,30 +71,42 @@ Effective communication is a cornerstone of societal cohesion, and this project
 
 You can read the project proposal here, [Project Proposal](https://github.com/AISaturdaysLagos/Cohort8-Ransome-Kuti-Ladipo/blob/main/project-proposal.pdf)
 
-[![DEMO][product-screenshot]](https://example.com)
-![sign_lang_gif](images/sign_lang.gif)
-
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
 ### Built With
 
 - [![Python][Python]][Python-url]
 - [![Pytorch][Pytorch]][Pytorch-url]
+- [![GCP][GCP]][GCP-URL]
+- [![MEAT][META]][META-url]
 - [![HuggingFace][HuggingFace]][HuggingFace-url]
 
-
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
-<!-- GETTING STARTED -->
-## Getting Started
+> [!NOTE]
+> Currently, our support is exclusively for the Yoruba language.\
+However, we aspire to expand our services to include other low-resource Nigerian languages such as Igbo and Hausa in the future.
 
-The project is structured into three distinct parts, each housed in separate directories as outlined in the project proposal. The initial phase involves translating sign language into English text, followed by the second phase, which focuses on translating the English text into Yoruba text. The final segment entails taking the translated Yoruba text and converting it into generated Yoruba audio.
+## Demos
 
-The `signa2text` directory is dedicated to the process of translating sign language into English text. Meanwhile, the `linguify_yb` directory serves the purpose of transforming English text into Yoruba text. Finally, the `yb2audio` directory is designated for utilizing the translated audio to generate Yoruba audio.
+> This is a Temporary demo
+
+[![Video Title](https://img.youtube.com/vi/YOUTUBE_VIDEO_ID_HERE/0.jpg)](https://www.youtube.com/watch?v=YOUTUBE_VIDEO_ID_HERE)
+
+## System Architecture
+
+<!--[high_level_system_design](images) -->
+### Architecture of Inference Pipeline
+
+![inference_pipeline.gif](.assets/inference_pipeline.gif.gif)
+
+### System Design
+
+![system_design](.assets\system_design)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
 
-To access any of the three directories, adhere to the specified prerequisites below and navigate into the respective directory.
+## Quick Start
 
-### Prerequisites
+The easiest way to run the project locally:
 
 ```bash
 # Clone this repository
@@ -111,50 +115,34 @@ $ git clone https://github.com/rileydrizzy/NSL_2_AUDIO
 # Go into the repository
 $ cd NSL_2_AUDIO
 
-# Install dependencies
-$ make setup
-```
+# Go to app directory
+$ cd app
 
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
+```
 
-<!-- USAGE EXAMPLES -->
-## Usage
+<!-- GETTING STARTED -->
+## Getting Started
 
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
+The project is structured into three distinct parts, each housed in separate directories as outlined in the project proposal. The initial phase involves translating sign language into English text, followed by the second phase, which focuses on translating the English text into Yoruba text. The final segment entails taking the translated Yoruba text and converting it into generated Yoruba audio.
 
-<!-- ROADMAP -->
-## Roadmap
+The `signa2text` directory is dedicated to the process of translating sign language into English text. Meanwhile, the `linguify_yb` directory serves the purpose of transforming English text into Yoruba text. Finally, the `yb2audio` directory is designated for utilizing the translated audio to generate Yoruba audio.
 
-- [ ] Feature 1
+In the `app` directory, hold the logic for the application. This directory serves as the core repository for all the essential functionalities and trained models required for the smooth operation of the application. Here, you'll find the code responsible for handling user interactions, processing of video data, managing state, and performing inference.
 
-See the [open issues](https://github.com/rileydrizzy/NSL_2_AUDIO/issues) for a full list of proposed features (and known issues).
+**To access any of the directories, navigate into the respective directory and adhere to the specified prerequisites in the respective directory README.**
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
-<!-- CONTRIBUTING -->
-## Contributing
+## :bulb: Roadmap
 
-Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
-
-If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
-Don't forget to give the project a star! Thanks again!
-
-1. Fork the Project
-2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the Branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
+## Contributing
 
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
+We welcome contributions to enhance NSL-2-AUDIO capabilities and improve its performance. To contribute, please see the `CONTRIBUTING.md` file for steps.
 
-<!-- LICENSE -->
 ## License
 
-Distributed under the MIT License. See `LICENSE` for more information.
+NSL-2-AUDIO is released under the [MIT License](https://opensource.org/licenses/MIT). See the `LICENSE` file for more information.
 
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
-<!-- CONTACT -->
 ## Contact
 
 If you have questions or need assistance, feel free to reach out to:
@@ -164,8 +152,6 @@ If you have questions or need assistance, feel free to reach out to:
 **GitHub:** [@rileydrizzy](https://github.com/rileydrizzy)  
 **Linkdeln:** [Ipadeola Ladipo](https://www.linkedin.com/in/ladipo-ipadeola/)
 
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
-
 <!-- ACKNOWLEDGMENTS -->
 ## Acknowledgments
 
@@ -191,12 +177,13 @@ I would like to acknowledge the outstanding contributions of :
 [issues-url]: https://github.com/rileydrizzy/NSL_2_AUDIO/issues
 [license-shield]: https://img.shields.io/github/license/rileydrizzy/NSL_2_AUDIO.svg?style=for-the-badge
 [license-url]: https://github.com/rileydrizzy/NSL_2_AUDIO/blob/master/LICENSE.txt
-[product-screenshot]: images/screenshot.png
 [Python-url]: <https://www.python.org/>
 [Python]: <https://img.shields.io/badge/Python-563D7C?style=for-the-badge&logo=python&logoColor=white>
 [Pytorch-url]: <https://pytorch.org/>
 [Pytorch]: <https://img.shields.io/badge/PyTorch-0769AD?style=for-the-badge&logo=pytorch&logoColor=white>
+[GCP-url]: <https://cloud.google.com/>
+[GCP]: <https://img.shields.io/badge/Google-0769AD?style=for-the-badge&logo=googlecloud&logoColor=white>
 [HuggingFace-url]: <https://huggingface.co/>
-[HuggingFace]: <https://img.shields.io/badge/HuggingFace-DD0031?style=for-the-badge&logo=huggingface&logoColor=white>
-[GCP-url]: <https://cloud.google.com/?hl=en>
-[GCP]: <>
+[HuggingFace]: <https://img.shields.io/badge/HuggingFace-DD0031?style=for-the-badge&logo=Huggingface&logoColor=white>
+[META-url]: <https://ai.meta.com/>
+[META]: <https://img.shields.io/badge/meta-563D7C?style=for-the-badge&logo=meta&logoColor=white>

app/streamlit_app/app.py

@@ -101,7 +101,6 @@
 st.divider()
 
 # Introduction section
-st.subheader("intro")
 st.markdown("**<u> INTRODUCTION </u>**", unsafe_allow_html=True)
 st.markdown(
     "<div style='text-align: justify;'><p style='text-indent: 2em;'>"

app/streamlit_app/components/configs.py

@@ -32,8 +32,8 @@
 RESULT_PAGE = PAGES_DIR + "result_page.py"
 PROJECT_LOGO = "assets/images/logos/logo.png"
 NSL_SIGN_GIF = "assets/sign_lang.gif"
-LOADING_ANIMATION = "assets/lotties/Animation_1708486960708.json"
-PROCESSING_ANIMATION = "assets/lotties/Animation_1708486960708.json"
+LOADING_ANIMATION = "assets/lottie/Animation_1708486960708.json"
+PROCESSING_ANIMATION = "assets/lottie/Animation_1708486960708.json"
 
 # Slideshow images
 SLIDES_IMAGES = [
@@ -246,7 +246,7 @@
 </style>
 <div class="footer">
     <p style="font-size: 13px">Copyright (c) 2024 Ladipo Ezekiel Ipadeola.</p>
-    <p style="font-size: 13px">This software is distributed under an M!T licence. Please consult the LICENSE file for more details.</p>
+    <p style="font-size: 13px">This software is distributed under an M!T license. Please consult the LICENSE file for more details.</p>
     <a href="https://github.com/rileydrizzy/NSL_2_AUDIO"><img class="image2" src="https://cdn-icons-png.flaticon.com/512/25/25231.png" alt="github" width="70" height="70"></a>
 </div>
 """

app/streamlit_app/components/utils.py

@@ -4,7 +4,9 @@
 Functions:
 - `load_lottiefile(filepath: str) -> dict`: Loads a Lottie animation file (.json) \
     and returns its parsed contents as a dictionary.
-- extract_landmarks_features()
+- `extract_landmarks_features(video_file, startframe)`: Extracts landmarks features \
+    from the uploaded NSL video file.
+
 
 Dependencies:
 - cv2
@@ -17,11 +19,10 @@
 
 """
 
-#import cv2
 import json
-#import numpy as np
-#import pandas as pd
-#import mediapipe as mp
+import cv2
+import pandas as pd
+import mediapipe as mp
 
 
 def load_lottiefile(filepath: str) -> dict:
@@ -53,7 +54,7 @@ def load_lottiefile(filepath: str) -> dict:
 
 
 # TODO Debug
-""""def extract_landmarks_features(cap, start_frame=0):
+def extract_landmarks_features(cap, start_frame=0):
 
     if not isinstance(cap, cv2.VideoCapture):
         raise ValueError
@@ -180,4 +181,3 @@ def load_lottiefile(filepath: str) -> dict:
     return pd.DataFrame(
         {"frame": frame, "type": type_, "landmark_index": index, "x": x, "y": y, "z": z}
     )
-"""