Project Sentry: A Digital Fingerprinting and Authentication System for Tangible Cultural Heritage

This repository contains the full source code for Project Sentry, a thesis project for the Bachelor of Science in Computer Engineering at Bulacan State University.

The primary goal of this project is to design and build a low-cost, dual-mode desktop station capable of generating a unique and verifiable digital fingerprint (a "perceptual hash") for a wide range of tangible cultural artifacts.

Features

• Dual-Mode Scanning: Supports both 3D volumetric objects (like pottery, sculptures) and 2D planar objects (like paintings, documents).
• Automated Data Capture: Utilizes a mechatronic system with a turntable and gantry for consistent, repeatable image acquisition.
• Volumetric Hashing: Generates a unique hash from a 3D model's geometric shape using photogrammetry and Principal Component Analysis (PCA) for normalization.
• Textural Hashing: Generates a unique hash from a 2D surface's microscopic texture using photometric stereo.
• Low-Cost & Open-Source: Built with accessible components and open-source software to provide a scalable solution for institutions with limited budgets.

System Architecture

The project is built on a Controller-Processor model:

• Controller (Raspberry Pi): A dedicated, headless hardware server that controls the station's mechatronics (motors, lights, camera). It runs a lightweight Flask bridge to expose hardware and capture functions over the network.
• Processor (Host PC): A powerful client application (running on Windows or Linux) that commands the Controller, receives the captured image data, and performs all computationally intensive tasks (3D reconstruction, normal map calculation, normalization, and hashing).

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

You will need the following software installed on your system:

• Git (Download here)
• Python 3.9 or higher (Download from python.org for Windows).
  • IMPORTANT (Windows): During installation, make sure to check the box that says "Add Python to PATH".

Installation

Follow these steps to set up your development environment.

1. Clone the repository: Open a terminal (Command Prompt, PowerShell, or Git Bash on Windows; a standard terminal on Linux).

   git clone git@github.com:DevMortimer/ProjectSentry
   cd ProjectSentry
   

2. Create and activate the Python virtual environment:

   On Windows (in Command Prompt):

   python -m venv venv
   venv\Scripts\activate
   

   (Your command prompt should now be prefixed with (venv))

   On Linux/macOS:

   python3 -m venv venv
   source venv/bin/activate
   

   (Your terminal prompt should now be prefixed with (venv))

3. Install the required Python packages: This project uses separate requirements files for the PC and the Raspberry Pi. For development on your main PC, you only need the common libraries. Ensure your virtual environment is active before running this command.

   pip install -r requirements.txt
   

   (When deploying to the Raspberry Pi, you will run pip install -r requirements.txt -r requirements-pi.txt to include hardware-specific libraries.)

4. Install System Dependencies (Important!) Computer vision libraries like OpenCV and Open3D sometimes rely on system libraries that are not installed by pip. If you encounter errors, especially on a fresh OS install, you may need the following:

   On Windows: Generally, pip handles most dependencies on Windows. However, you may need the Microsoft C++ Build Tools. If you get errors during pip install, download the "Build Tools for Visual Studio" and install the "C++ build tools" workload.

   On Linux (Debian/Ubuntu):

   sudo apt-get update && sudo apt-get install -y libx11-6 libgl1-mesa-glx
   

Usage (Testing the 3D Hashing Pipeline)

This is a quick test to verify that the core 3D hashing algorithm is working correctly.

1. Place a 3D model file (e.g., in .stl or .obj format) into the sentry\processor\data\ directory. For example, let's assume it is named sample_model.stl. (Note the use of \ for Windows paths and / for Linux paths).

2. Modify the script: Open sentry/processor/hash_3d.py and ensure the MODEL_FILE_PATH variable at the bottom points to your model file. Use a forward slash / in the path for cross-platform compatibility (Python handles this correctly).

   # Example
   MODEL_FILE_PATH = "sentry/processor/data/sample_model.stl"
   

3. Run the script from the project's root directory: Ensure your virtual environment is active.

   On Windows (in Command Prompt):

   python sentry\processor\hash_3d.py
   

   On Linux/macOS:

   python sentry/processor/hash_3d.py
   

4. Expected Output: The script will print its progress and, upon completion, display the final volumetric hash:

   1. Loading model from sentry/processor/data/sample_model.stl...
      ...Loaded XXXXX vertices.
   2. Normalizing model orientation with PCA...
      ...Normalization complete.
   3. Generating Volumetric Hash...
      ...Hashing complete.
   
   ========================================
   SUCCESS! Volumetric Hash Generated:
   a4c1f9e2b4d681c3a4f8d9b3c1e5a7b2...
   ========================================