Metadata-Version: 2.1
Name: smartlocate
Version: 2025.1.7.post3
Summary: Similiar to locate, but looks at the content
Home-page: https://github.com/NormanTUD/smartlocate
Author: Norman Koch
Author-email: norman.koch@tu-dresden.de
Platform: Linux
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch
Requires-Dist: yolov5
Requires-Dist: rich
Requires-Dist: sixel
Requires-Dist: easyocr
Requires-Dist: transformers
Requires-Dist: face-recognition
Requires-Dist: rich-argparse

# smartlocate - YOLO and OCR File Indexer

smartlocate is a tool for Linux that uses YOLO (You Only Look Once) to detect objects in images and creates a database of detected objects. This database is stored locally and allows you to search for specific objects in images. smartlocate uses an SQLite database to efficiently store and search image data.

If the parameter `--ocr` is set while indexing, all images are also OCRed and the found text is searchable. You can set the language with `--lang_ocr tr` for example. Default is `["de", "en"]`.

If the parameter `--describe` is set while indexing, the model `Salesforce/blip-image-captioning-large` will be used to generate descriptions of images automatically, which also then can be searched.

<p align="center">
<img src="https://raw.githubusercontent.com/NormanTUD/smartlocate/refs/heads/main/images/index.gif" alt="Indexing" width="1046"/>
</p>

<p align="center">
<img src="https://raw.githubusercontent.com/NormanTUD/smartlocate/refs/heads/main/images/face_recognition.gif" alt="Face Recognition" width="1046"/>
</p>

<p align="center">
<img src="https://raw.githubusercontent.com/NormanTUD/smartlocate/refs/heads/main/images/dog.gif" alt="Search: Dog" width="1046"/>
</p>

<p align="center">
<img src="https://raw.githubusercontent.com/NormanTUD/smartlocate/refs/heads/main/images/cat.gif" alt="Search: Cat" width="1046"/>
</p>

<p align="center">
<img src="https://raw.githubusercontent.com/NormanTUD/smartlocate/refs/heads/main/images/ocr.gif" alt="OCR" width="1046"/>
</p>

## Features

- Object detection in images using YOLO.
- OCR is done via easyocr, when `--ocr` was set during indexing. Allows you to use `%` as a wildcard.
- Stores detected objects in a local SQLite database (`~/.smartlocate_db`).
- Fast searching for specific objects in images.
- Supports Sixel graphics for visualizing results.
- Easy to install and use.
- Automatic face recognition (use `--face_recognition` while indexing). It will ask you (hopefully only once) per person what their name is, so it can recognize them later on automatically.

## Installation

1. Clone the repository:

```bash
   git clone --depth 1 https://github.com/NormanTUD/smartlocate.git
```

2. Navigate to the directory and run the following command to install the tool:

```bash
cd smartlocate
./smartlocate --index --dir ~/Pictures
```

smartlocate will automatically install all necessary dependencies, and YOLO is already included. This is done on first execution, which may take some time. But this only has to be done once!

# Usage

## Indexing Images

To index images in a specific directory, run the following command:

```bash
smartlocate --dir /path/to/images --index
```

YOLO will be used to detect objects, and the results will be stored in the database. You need to re-run the index every time new images are added or changed.

## Searching for Objects

To search for a specific object (e.g., "cat"), run the following command:

```bash
smartlocate cat
```

The tool will search the indexed images for the object and display the results.

## Additional Options

- `--index`: Indexes images in the specified directory.
- `--size SIZE`: Specifies the size to which images should be resized when indexing. Default is 400.
- `--dir DIR`: Specifies the directory to search or index.
- `--debug`: Enables debug mode to output detailed logs.
- `--no_sixel`: Hide Sixel graphics.
- `--describe`: Saves descriptions of images (generated by AI) as well and makes them searchable
- `--exact`: Searches exactly what is entered, without splitting
- `--ocr`: Enable OCR.
- `--lang_ocr`: OCR languages, default: de, en. Accepts multiple languages.
- `--delete_non_existing_files`: Deletes non-existing files from the database.
- `--shuffle_index`: Shuffles the list of files before indexing.
- `--model MODEL`: Specifies the YOLO model for object detection.
- `--threshold THRESHOLD`: Sets the confidence threshold for object detection (0-1).
- `--dbfile DBFILE`: Specifies the path to the SQLite database file.
- `--exclude PATH`: Excludes a path from indexing/searching. Can be used multiple times.
- `--dont_ask_new_faces`: Don't ask for new faces (useful for automatically tagging all photos that can be tagged automatically).

# Example Commands

## Indexing images in a directory:

```bash
smartlocate --dir /home/user/images --index
```

## Search for images containing the object "cat":

```bash
smartlocate cat
```

## Indexing:

Indexing with YOLO, Description and OCR:

```bash
smartlocate --dir /home/user/images --index --debug --ocr --describe
```

# Database

The results of image indexing are stored in the SQLite database `~/.smartlocate_db`. This database contains information about detected
objects in the images. The index must be re-run whenever new images are added or changes are made.

# Manage single images

Simply run `smartlocate /path/to/an/image/file.jpg` to see an overview of the image file's data and modify it.

# Requirements

- Python 3.x
- All dependencies will be automatically installed when the tool is first run.


# Ideas

Future ideas would be to expand this to other formats than images as well. Imagine you could say:

```bash
smartlocate "text about cats"
```

and get all `.txt`, `.md`, `.docx` and so on files in which something about cats is written.

Same for videos and audio files. If someone wants to do it, feel free to contribute!

# License

Licensed under GPL2.
