{"id":29311544,"url":"https://github.com/deshan555/lostfound","last_synced_at":"2026-05-10T05:05:41.147Z","repository":{"id":302769074,"uuid":"1003383865","full_name":"Deshan555/lostFound","owner":"Deshan555","description":"A robust FastAPI-based system enhanced with image matching capabilities for managing and filtering lost item records. This system integrates MySQL for database management, stores image files on a local VM, and provides a scalable backend with an optional frontend interface.","archived":false,"fork":false,"pushed_at":"2025-07-04T05:21:50.000Z","size":123,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-04T06:26:41.230Z","etag":null,"topics":["fastapi","image-mat","image-recognition","lost-found-backend","mysql-database","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Deshan555.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-17T04:23:30.000Z","updated_at":"2025-07-04T05:21:52.000Z","dependencies_parsed_at":"2025-07-04T06:37:14.965Z","dependency_job_id":null,"html_url":"https://github.com/Deshan555/lostFound","commit_stats":null,"previous_names":["deshan555/lostfound"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Deshan555/lostFound","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Deshan555%2FlostFound","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Deshan555%2FlostFound/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Deshan555%2FlostFound/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Deshan555%2FlostFound/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Deshan555","download_url":"https://codeload.github.com/Deshan555/lostFound/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Deshan555%2FlostFound/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264040974,"owners_count":23548077,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","image-mat","image-recognition","lost-found-backend","mysql-database","rest-api"],"created_at":"2025-07-07T08:15:08.851Z","updated_at":"2026-05-10T05:05:41.120Z","avatar_url":"https://github.com/Deshan555.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lost \u0026 Found Project\n\nA robust FastAPI-based system enhanced with image matching capabilities for managing and filtering lost item records. This system integrates MySQL for database management, stores image files on a local VM, and provides a scalable backend with an optional frontend interface.\n\n![Alt text](system.png)\n\n## Project Overview\n\nThe Lost \u0026 Found Project enables users to:\n- Report lost items with details including images, item type, description, date lost, and location.\n- Perform image-based matching to identify similar lost items using OpenCV's ORB feature detection.\n- Filter and search records based on various criteria (e.g., item type, date range, location).\n- Manage records via a RESTful API with MySQL as the backend database.\n\nThe system leverages FastAPI, SQLAlchemy, Pydantic, OpenCV, and MySQL, with an optional React-based frontend using TypeScript.\n\n## Project Structure\n\nThe project is organized into `backend` and `frontend` directories. Below is the detailed folder structure:\n\n```\nlost-and-found/\n├── backend/\n│   ├── __init__.py                # Marks directory as Python package\n│   ├── main.py                    # FastAPI application entry point\n│   ├── actions/\n│   │   ├── __init__.py            # Marks directory as Python package\n│   │   ├── lostRecords_action.py  # Actions related to lost item operations\n│   │   └── user_actions.py        # Actions related to user operations\n│   ├── auth/\n│   │   ├── __init__.py            # Marks directory as Python package\n│   │   └── auth.py                # Authentication logic\n│   ├── config/\n│   │   ├── __init__.py            # Marks directory as Python package\n│   │   ├── connectionCheck.py     # Database connection checks\n│   │   ├── database.py            # Database configuration\n│   │   └── dbinit.py              # Database initialization\n│   ├── models/\n│   │   ├── __init__.py            # Marks directory as Python package\n│   │   ├── document.py            # Model for document-related lost items\n│   │   ├── electronics.py         # Model for electronics lost items\n│   │   ├── findRecords.py         # Model for record retrieval logic\n│   │   ├── jewelry.py             # Model for jewelry lost items\n│   │   ├── lostRecords.py         # Core model for lost items\n│   │   ├── others.py              # Model for miscellaneous lost items\n│   │   ├── pets.py                # Model for pet-related lost items\n│   │   ├── policeStationData.py   # Model for police station data\n│   │   ├── users.py               # Model for user data\n│   │   └── wallet.py              # Model for wallet-related lost items\n│   ├── schemas/\n│   │   ├── __init__.py            # Marks directory as Python package\n│   │   ├── custom_response.py     # Custom response schemas\n│   │   ├── documents_schema.py    # Schema for document-related items\n│   │   ├── electronics_schema.py  # Schema for electronics items\n│   │   ├── jewelry_schema.py      # Schema for jewelry items\n│   │   ├── lostRecords_schema.py  # Core schema for lost items\n│   │   ├── others_schema.py       # Schema for miscellaneous items\n│   │   ├── pets_schema.py         # Schema for pet-related items\n│   │   ├── user_schema.py         # Schema for user data\n│   │   └── wallets_schema.py      # Schema for wallet-related items\n│   ├── services/\n│   │   ├── __init__.py            # Marks directory as Python package\n│   │   ├── lostRecords.py         # Service layer for lost item operations\n│   │   ├── uploads.py             # Service for handling image uploads\n│   │   └── user.py                # Service layer for user operations\n│   ├── static/\n│   │   ├── env                    # Environment configuration\n│   │   ├── image.py               # Image handling utilities\n│   │   └── image-match.py         # Image matching logic\n│   └── requirements.txt           # Python dependencies\n├── frontend/\n│   ├── package.json               # Node.js dependencies and scripts\n│   ├── tsconfig.json              # TypeScript configuration\n│   ├── src/\n│   │   ├── index.tsx              # Frontend entry point\n│   │   ├── components/            # Reusable React components\n│   │   ├── pages/                 # Page-specific components\n│   │   ├── styles/                # CSS or Tailwind CSS styles\n│   │   └── assets/                # Static assets\n├── .gitignore                     # Git ignore file\n├── README.md                      # Project documentation (this file)\n└── docker-compose.yml             # Optional Docker configuration\n```\n\n### Directory Descriptions\n\n- **`backend/`**: Contains all backend-related code.\n  - **`main.py`**: Initializes the FastAPI app and mounts routers.\n  - **`actions/`**: Defines business logic actions.\n    - `lostRecords_action.py`: Handles lost item CRUD operations.\n    - `user_actions.py`: Manages user-related actions.\n  - **`auth/`**: Authentication module.\n    - `auth.py`: Implements user authentication logic.\n  - **`config/`**: Configuration and database setup.\n    - `connectionCheck.py`: Verifies database connectivity.\n    - `database.py`: Configures MySQL engine and session.\n    - `dbinit.py`: Initializes the database schema.\n  - **`models/`**: SQLAlchemy ORM models for various item types and users.\n  - **`schemas/`**: Pydantic models for data validation.\n  - **`services/`**: Service layer for business logic.\n    - `uploads.py`: Manages image uploads to the local VM.\n  - **`static/`**: Utilities for environment and image handling.\n    - `image-match.py`: Contains image matching logic using OpenCV.\n  - **`requirements.txt`**: Lists dependencies (e.g., `fastapi`, `sqlalchemy`, `pydantic`, `opencv-python`, `mysql-connector-python`).\n\n- **`frontend/`**: Optional React-based UI.\n  - **`src/`**: Contains frontend source code with components, pages, styles, and assets.\n\n- **`.gitignore`**: Excludes files like `__pycache__` and `node_modules`.\n- **`docker-compose.yml`**: (Optional) Defines services for backend and MySQL.\n\n## Data \u0026 ORM\n\n- **Database**: MySQL stores lost item records and user data on a local VM.\n- **ORM Models** (`models/`): Define tables for various item types (e.g., `lostRecords.py` for core lost items).\n- **Session Management** (`config/database.py`): Configures MySQL connection and session factory.\n\n## Endpoints \u0026 Models\n\n- **`POST /lost`**: Creates a lost item with an optional image.\n- **`POST /lost/custom`**: Filters lost items based on criteria.\n- **`POST /lost/match`**: Performs image matching and returns similar items.\n\n## Image Matching\n\nThe system includes an image matching feature using OpenCV's ORB algorithm, storing images on a local VM. The `image-match.py` file contains the following function:\n\n```python\nimport cv2\nimport os\nimport json\nfrom pathlib import Path\n\ndef feature_matching(query_image_path, folder_path, min_matches=10):\n    \"\"\"\n    Perform feature matching between a query image and all images in a folder.\n    Returns results as a JSON array with image paths and match counts.\n    \"\"\"\n    orb = cv2.ORB_create()\n    query_img = cv2.imread(query_image_path, cv2.IMREAD_GRAYSCALE)\n    if query_img is None:\n        raise ValueError(f\"Could not load query image: {query_image_path}\")\n    query_kp, query_desc = orb.detectAndCompute(query_img, None)\n    if query_desc is None:\n        raise ValueError(\"No descriptors found in query image\")\n    matcher = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=False)\n    results = []\n    for img_path in Path(folder_path).glob(\"*.[jp][pn][gf]\"):\n        img = cv2.imread(str(img_path), cv2.IMREAD_GRAYSCALE)\n        if img is None:\n            continue\n        kp, desc = orb.detectAndCompute(img, None)\n        if desc is None:\n            continue\n        matches = matcher.knnMatch(query_desc, desc, k=2)\n        good_matches = [m for m, n in matches if m.distance \u003c 0.75 * n.distance]\n        if len(good_matches) \u003e= min_matches:\n            results.append({\n                \"image_path\": str(img_path),\n                \"match_count\": len(good_matches)\n            })\n    return sorted(results, key=lambda x: x[\"match_count\"], reverse=True)\n\ndef save_results_to_json(results, output_json_path):\n    \"\"\"\n    Save the matching results to a JSON file.\n    \"\"\"\n    with open(output_json_path, 'w') as f:\n        json.dump(results, f, indent=4)\n\ndef main():\n    query_image_path = \"samples/image.jpeg\"\n    folder_path = \"samples\"\n    output_json_path = \"matching_results.json\"\n    try:\n        results = feature_matching(query_image_path, folder_path)\n        save_results_to_json(results, output_json_path)\n        print(f\"Results saved to {output_json_path}\")\n        print(json.dumps(results, indent=4))\n    except Exception as e:\n        print(f\"Error: {str(e)}\")\n\nif __name__ == \"__main__\":\n    main()\n```\n\n## Setup Instructions\n\n1. **Clone the Repository**:\n   ```bash\n   git clone https://github.com/username/lost-and-found.git\n   cd lost-and-found\n   ```\n\n2. **Set Up the Backend**:\n   - Install Python 3.8+ and create a virtual environment.\n   - Install dependencies:\n     ```bash\n     pip install -r backend/requirements.txt\n     ```\n   - Configure MySQL on the local VM and update `config/database.py` with credentials.\n\n3. **Set Up the Frontend** (Optional):\n   - `cd frontend` and run `npm install`.\n   - Start the frontend: `npm start`.\n\n4. **Run the Application**:\n   ```bash\n   uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload\n   ```\n\n5. **Access the API**:\n   - Visit [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) for API documentation.\n\n## Dependencies\n\n- Backend: `fastapi`, `sqlalchemy`, `pydantic`, `opencv-python`, `mysql-connector-python`.\n- Frontend: `react`, `typescript`, `axios`.\n\n## Development Notes\n\n- **Image Storage**: Images are stored on a local VM; update `folder_path` in `image-match.py` accordingly.\n- **MySQL**: Ensure the database is initialized with `dbinit.py`.\n- **Testing**: Use `pytest` for backend and `jest` for frontend.\n\n## Contributing\n\nFork the repository, create a feature branch, commit changes, and open a pull request.\n\n## License\n\nMIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeshan555%2Flostfound","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeshan555%2Flostfound","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeshan555%2Flostfound/lists"}