diff --git a/docs/configuration.md b/docs/configuration.md index 6dcf2d11..7c920672 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,18 +1,18 @@ # Configuration -PhotoMap is primarily configured through the web interface as described in [Basic Usage](user-guide/basic-usage.md#changing-settings) and [Albums](user-guide/albums.md). However, there are a number of runtime parameters that control how the web service behaves. +PhotoMapAI is primarily configured through the web interface as described in [Basic Usage](user-guide/basic-usage.md#changing-settings) and [Albums](user-guide/albums.md). However, there are a number of runtime parameters that control how the web service behaves. ## Changing the Web Host and Port -By default, PhotoMap runs its web service on port 8050 and only accepts connections on the local machine (`localhost`). These can be changed on the command line used to launch the application using the `--port` and `--host` options: +By default, PhotoMapAI runs its web service on port 8050 and only accepts connections on the local machine (`localhost`). These can be changed on the command line used to launch the application using the `--port` and `--host` options: start_photomap --port 8000 --host 0.0.0.0 -This command changes the port to port 8000, and allows PhotoMap to listen for connections on the wildcard IP address `0.0.0.0`, meaning that it will accept connections for any network-accessible location. +This command changes the port to port 8000, and allows PhotoMapAI to listen for connections on the wildcard IP address `0.0.0.0`, meaning that it will accept connections for any network-accessible location. -If you are using a launcher script to start PhotoMap (e.g. `start_photomap.bat`) you can change these values by opening the script in a text editor (`Notepad` on Windows), finding the line containing `start_photomap`, and adding the options as shown above. +If you are using a launcher script to start PhotoMapAI (e.g. `start_photomap.bat`) you can change these values by opening the script in a text editor (`Notepad` on Windows), finding the line containing `start_photomap`, and adding the options as shown above. -Alternatively, you can change the port and host interface by setting two environment variables prior to launching PhotoMap. These are: +Alternatively, you can change the port and host interface by setting two environment variables prior to launching PhotoMapAI. These are: * `PHOTOMAP_HOST` - the host interface to accept connections from * `PHOTOMAP_PORT` - the listen port @@ -27,16 +27,16 @@ Or you can permanently fix these environment variables by setting them in your s On Windows systems, setting environment variables can be done through the GUI as well as on the command line. See [How to Set Environment Variables in Windows](https://phoenixnap.com/kb/windows-set-environment-variable) for a good walkthrough. -## Running PhotoMap Under HTTPS +## Running PhotoMapAI Under HTTPS -By default, PhotoMap runs as a non-secure `HTTP` service. This generates a warning icon in some browsers, but more seriously prevents cut and paste between the PhotoMap tab and browser tabs and desktop applications. +By default, PhotoMapAI runs as a non-secure `HTTP` service. This generates a warning icon in some browsers, but more seriously prevents cut and paste between the PhotoMapAI tab and browser tabs and desktop applications. -There are several ways to enable HTTP for PhotoMap: +There are several ways to enable HTTP for PhotoMapAI: ### Install a Self-Signed SSL Certificate In this method, you generate self-signed encryption certificate and -private key files and point PhotoMap to them using its `--cert` and +private key files and point PhotoMapAI to them using its `--cert` and `--key` command-line options. Guides to generating and installing self-signed certificates: @@ -46,14 +46,14 @@ Guides to generating and installing self-signed certificates: - [Creating Self-Signed Certificates with OpenSSL (Mac/Linux)](https://gist.github.com/elklein96/a15090f35a41e16bdc8574a7fb81e119) These methods will leave you with two files, a .crt certificate file, -and a .pem key file. Relaunch the PhotoMap server using `--cert +and a .pem key file. Relaunch the PhotoMapAI server using `--cert /path/to/.crt file` and `--key /path/to/.pem file`. If you are using the desktop launcher to start the server, simply open the launcher file with a text editor, and add the `--cert` and `--key` options to the end of the line that ends with `start_photomap`. After installing the certificate/key pair and relaunching the server, -you will be able to access the PhotoMap server using the https:// +you will be able to access the PhotoMapAI server using the https:// URL. Your browser will complain about an unknown certificate authority when you first load the URL and ask you to confirm that you trust the site. @@ -64,14 +64,14 @@ browsers automatically trust. It is very easy to use, but it requires that you have a web running on port 80 that accepts incoming HTTP connections. Once the Certbot certificate and keyfile are generated, follow the -directions in the previous section to configure PhotoMap to use them. +directions in the previous section to configure PhotoMapAI to use them. ### Use a Reverse Proxy -A final option is to keep PhotoMap running on HTTP, but use a reverse +A final option is to keep PhotoMapAI running on HTTP, but use a reverse proxy from a running web server to translate HTTPS requests on the -reverse proxy into HTTP requests to PhotoMap. The main advantage of this +reverse proxy into HTTP requests to PhotoMapAI. The main advantage of this is that you get the additional benefit of all the web server's configuration controls, such as the ability to add password protection. @@ -89,12 +89,12 @@ You will need to install encryption certificates for the Nginx server using [Cer This is saying that when a request comes in for `https://your.host/photomap/` it will be translated into a request to -`http://localhost:8050/` where PhotoMap is running. It is possible to -run the proxy server and the PhotoMap server on separate machines as well. +`http://localhost:8050/` where PhotoMapAI is running. It is possible to +run the proxy server and the PhotoMapAI server on separate machines as well. ## Pointing to an Alternative Configuration File -PhotoMap stores its album definitions and other configuration information in a configuration file. It is not usually necessary to manipulate it directly, but if you wish you can point to an alternative config file in order to have multiple PhotoMap servers each hosting separate album collections. +PhotoMapAI stores its album definitions and other configuration information in a configuration file. It is not usually necessary to manipulate it directly, but if you wish you can point to an alternative config file in order to have multiple PhotoMapAI servers each hosting separate album collections. The config file is stored in different places depending on the platform: @@ -104,11 +104,11 @@ The config file is stored in different places depending on the platform: | MacOS | ~/Library/Application Support/photomap/config.yaml | | Windows | C:\Users\\AppData\Roaming\photomap\config.yaml| -To run PhotoMap off a different config file, you may launch it with the `--config` option on the command line, similar to setting the port and host. In the below example we specify an alternative config file named `photomap_2.yaml` +To run PhotoMapAI off a different config file, you may launch it with the `--config` option on the command line, similar to setting the port and host. In the below example we specify an alternative config file named `photomap_2.yaml` start_photomap --config ~/photomap_2.yaml -If the indicated config file doesn't exist when you launch PhotoMap, it will be created automatically. +If the indicated config file doesn't exist when you launch PhotoMapAI, it will be created automatically. You may also point to an alternative configuration file by setting the environment variable `PHOTOMAP_CONFIG`, as described in the previous section: diff --git a/docs/developer/api.md b/docs/developer/api.md index 1e7bb7aa..085295c4 100644 --- a/docs/developer/api.md +++ b/docs/developer/api.md @@ -1,6 +1,6 @@ -# PhotoMap API Reference +# PhotoMapAI API Reference -PhotoMap is driven by a Pydantic data model and a series of FastAPI endpoints. You may access and test these endpoints using [http://localhost:8050/docs](http://localhost:8050/docs) +PhotoMapAI is driven by a Pydantic data model and a series of FastAPI endpoints. You may access and test these endpoints using [http://localhost:8050/docs](http://localhost:8050/docs) ## Album Management Endpoints diff --git a/docs/developer/architecture.md b/docs/developer/architecture.md index 8ad58753..ed31202a 100644 --- a/docs/developer/architecture.md +++ b/docs/developer/architecture.md @@ -1,12 +1,12 @@ -# PhotoMap Architecture +# PhotoMapAI Architecture -PhotoMap is a modular web application designed for efficient photo management, AI-powered search, and interactive visualization. Its architecture is organized into distinct layers and components to ensure scalability, maintainability, and ease of development. +PhotoMapAI is a modular web application designed for efficient photo management, AI-powered search, and interactive visualization. Its architecture is organized into distinct layers and components to ensure scalability, maintainability, and ease of development. --- ## Overview -PhotoMap consists of three main layers: +PhotoMapAI consists of three main layers: 1. **Frontend** - Built with HTML, CSS, and JavaScript (ES6 modules). diff --git a/docs/developer/frontend.md b/docs/developer/frontend.md index ae356698..90a53ec5 100644 --- a/docs/developer/frontend.md +++ b/docs/developer/frontend.md @@ -1,6 +1,6 @@ # Frontend Architecture -The PhotoMap frontend is a modular, responsive web application built with HTML, CSS, and JavaScript (ES6 modules). It provides an interactive user interface for browsing, searching, and visualizing photo collections. +The PhotoMapAI frontend is a modular, responsive web application built with HTML, CSS, and JavaScript (ES6 modules). It provides an interactive user interface for browsing, searching, and visualizing photo collections. --- diff --git a/docs/index.md b/docs/index.md index c125a296..2874c955 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,8 @@ -# PhotoMap +# PhotoMapAI Rediscover your photo collection! -PhotoMap is a fast, modern image browser and search tool for large photo collections. It supports text and image-based search, semantic clustering, and interactive slideshows with a responsive web interface. Its unique feature is a "semantic map" that clusters and visualizes your images by their content. Browse the semantic map to find and explore thematically-related groups of photos, or use text and/or image similarity search to find specific people, places, events, styles and themes. +PhotoMapAI is a fast, modern image browser and search tool for large photo collections. It supports text and image-based search, semantic clustering, and interactive slideshows with a responsive web interface. Its unique feature is a "semantic map" that clusters and visualizes your images by their content. Browse the semantic map to find and explore thematically-related groups of photos, or use text and/or image similarity search to find specific people, places, events, styles and themes.
Base image @@ -21,7 +21,7 @@ PhotoMap is a fast, modern image browser and search tool for large photo collect ## The Semantic Map -PhotoMap's unique feature is its ability to identify thematically similar images and automatically cluster them, creating a "semantic map": +PhotoMapAI's unique feature is its ability to identify thematically similar images and automatically cluster them, creating a "semantic map": Big Semantic Map @@ -31,7 +31,7 @@ You can move the semantic map around, shrink it down in size, or hide it altoget ## Text and Image Similarity Search -PhotoMap lets you search your collection by similarity to another image, by text, or by a combination of image and text as shown below: +PhotoMapAI lets you search your collection by similarity to another image, by text, or by a combination of image and text as shown below: Big Semantic Map @@ -49,7 +49,7 @@ If you are a user of the [InvokeAI](https://github.com/invoke-ai/InvokeAI) text- ## Other Features -PhotoMap supports most of the other features you would expect, including support for multiple separate photo albums, the ability to browse photos chronologically, an uncluttered fullscreen mode, and of course a configurable slideshow mode that can show images sequentially or shuffled. +PhotoMapAI supports most of the other features you would expect, including support for multiple separate photo albums, the ability to browse photos chronologically, an uncluttered fullscreen mode, and of course a configurable slideshow mode that can show images sequentially or shuffled. --- @@ -60,13 +60,13 @@ PhotoMap supports most of the other features you would expect, including support #### 1. Download and unpack the source code -Download the PhotoMap source code as a .zip file from the latest stable Releases page. For development versions, use the "Download ZIP" link in the green "Code" button near the top of the GitHub PhotoMap home page. +Download the PhotoMapAI source code as a .zip file from the latest stable Releases page. For development versions, use the "Download ZIP" link in the green "Code" button near the top of the GitHub PhotoMapAI home page. -Choose a convenient location in your home folder and unzip the file to create a new folder named `PhotoMap`. +Choose a convenient location in your home folder and unzip the file to create a new folder named `PhotoMapAI`. #### 2. Run the installer script -Navigate to the unpacked `PhotoMap` folder, find the `INSTALL` folder, and double-click the `install_windows` script file. The system will check that Python and other requirements are installed, download the necessary library files, and create a .bat script named `start_photomap`. +Navigate to the unpacked `PhotoMapAI` folder, find the `INSTALL` folder, and double-click the `install_windows` script file. The system will check that Python and other requirements are installed, download the necessary library files, and create a .bat script named `start_photomap`. #### 3. Start the server @@ -82,13 +82,13 @@ Double-click `start_photomap.bat` to launch the server. You should see a few sta #### 1. Download and unpack the source code -Download the PhotoMap source code as a .zip file from the latest stable Releases page. For development versions, use the "Download ZIP" link in the green "Code" button near the top of the GitHub PhotoMap home page. +Download the PhotoMapAI source code as a .zip file from the latest stable Releases page. For development versions, use the "Download ZIP" link in the green "Code" button near the top of the GitHub PhotoMapAI home page. -Choose a convenient location in your home directory and unzip the file to create a new folder named `PhotoMap`. +Choose a convenient location in your home directory and unzip the file to create a new folder named `PhotoMapAI`. #### 2. Run the installer script -Navigate to the `PhotoMap` folder and launch the `install_linux_mac` shell script file. The script will check that Python and other requirements are installed, download the necessary library files, and create a launcher script named `start_photomap` on your desktop. +Navigate to the `PhotoMapAI` folder and launch the `install_linux_mac` shell script file. The script will check that Python and other requirements are installed, download the necessary library files, and create a launcher script named `start_photomap` on your desktop. #### 3. Start the server diff --git a/docs/installation.md b/docs/installation.md index 2ed0adcc..2d74b314 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,6 +1,6 @@ # Installation -PhotoMap is a [Python](https://www.python.org/)-based web application that uses the [CLIP image recognition](https://openai.com/index/clip/) AI model to identify similarities among images, as well as to enable text- and image-similarity searching. It runs completely on your local system, and does not make calls out to internet-based AI systems. +PhotoMapAI is a [Python](https://www.python.org/)-based web application that uses the [CLIP image recognition](https://openai.com/index/clip/) AI model to identify similarities among images, as well as to enable text- and image-similarity searching. It runs completely on your local system, and does not make calls out to internet-based AI systems. ## Hardware Requirements @@ -10,13 +10,13 @@ PhotoMap is a [Python](https://www.python.org/)-based web application that uses * **CPU**: Any recent (post-2020) Intel or Apple CPU. * **GPU**: NVidia graphics card (optional) -If an NVidia graphics card is available, then PhotoMap will take advantage of it during the initial indexing of your photo collection for a 10x increase in indexing speed. You may need to install additional libraries to take advantage of this feature as described below. +If an NVidia graphics card is available, then PhotoMapAI will take advantage of it during the initial indexing of your photo collection for a 10x increase in indexing speed. You may need to install additional libraries to take advantage of this feature as described below. -PhotoMap will take advantage of the built-in GPU acceleration on Apple M1, M2 and M3 chips. +PhotoMapAI will take advantage of the built-in GPU acceleration on Apple M1, M2 and M3 chips. ## Installing Prerequisites -Before installing PhotoMap, you'll need to install Python and optionally CUDA. +Before installing PhotoMapAI, you'll need to install Python and optionally CUDA. - [Python](installation/python.md) - [CUDA](installation/cuda.md) (*Only if you need NVidia GPU card support*) @@ -30,13 +30,13 @@ After the preqrequisites are installed, follow the installation directions for [ ### 1. Download and unpack the source code -Download the PhotoMap source code as a .zip file from the latest stable Releases page. For development versions, use the "Download ZIP" link in the green "Code" button near the top of the GitHub PhotoMap home page. +Download the PhotoMapAI source code as a .zip file from the latest stable Releases page. For development versions, use the "Download ZIP" link in the green "Code" button near the top of the GitHub PhotoMapAI home page. -Choose a convenient location in your home folder and unzip the file to create a new folder named `PhotoMap`. +Choose a convenient location in your home folder and unzip the file to create a new folder named `PhotoMapAI`. ### 2. Run the installer script -Navigate to the unpacked `PhotoMap` folder, find the `INSTALL` folder, and double-click the `install_windows` script file. The system will check that Python and other requirements are installed, download the necessary library files, and create a .bat script named `start_photomap`. +Navigate to the unpacked `PhotoMapAI` folder, find the `INSTALL` folder, and double-click the `install_windows` script file. The system will check that Python and other requirements are installed, download the necessary library files, and create a .bat script named `start_photomap`. ### 3. Start the server @@ -46,7 +46,7 @@ Double-click `start_photomap.bat` to launch the server. You should see a few sta To exit the server, press ^C (control-C). -To relaunch the server, run the `start_photomap` .bat script again. For your convenience, you may move this script anywhere you like. Don't move the PhotoMap folder, or the script will not be able to find it again. If this happens, simply re-run the installer script to generate an updated launcher. +To relaunch the server, run the `start_photomap` .bat script again. For your convenience, you may move this script anywhere you like. Don't move the PhotoMapAI folder, or the script will not be able to find it again. If this happens, simply re-run the installer script to generate an updated launcher. --- @@ -54,13 +54,13 @@ To relaunch the server, run the `start_photomap` .bat script again. For your con ### 1. Download and unpack the source code -Download the PhotoMap source code as a .zip file from the latest stable Releases page. For development versions, use the "Download ZIP" link in the green "Code" button near the top of the GitHub PhotoMap home page. +Download the PhotoMapAI source code as a .zip file from the latest stable Releases page. For development versions, use the "Download ZIP" link in the green "Code" button near the top of the GitHub PhotoMapAI home page. -Choose a convenient location in your home directory and unzip the file to create a new folder named `PhotoMap`. +Choose a convenient location in your home directory and unzip the file to create a new folder named `PhotoMapAI`. ### 2. Run the installer script -Navigate to the `PhotoMap` folder and launch the `install_linux_mac` shell script file. The script will check that Python and other requirements are installed, download the necessary library files, and create a launcher script named `start_photomap` on your desktop. +Navigate to the `PhotoMapAI` folder and launch the `install_linux_mac` shell script file. The script will check that Python and other requirements are installed, download the necessary library files, and create a launcher script named `start_photomap` on your desktop. ### 3. Start the server @@ -70,7 +70,7 @@ Double click `start_photomap` to launch the server. You will see a few startup m To exit the server, press ^C (control-C). -To relaunch the server, run the `start_photomap` launcher again. For your convenience, you may move this script anywhere you like. If you move the PhotoMap folder itself, you will need to re-run the installer script. +To relaunch the server, run the `start_photomap` launcher again. For your convenience, you may move this script anywhere you like. If you move the PhotoMapAI folder itself, you will need to re-run the installer script. --- @@ -80,10 +80,10 @@ Download and unpack the source code as described in the sections above. Then fol ### 1. Create an installation directory for the executables -In a command line window, enter the PhotoMap folder and run the `pip` (Python package installer) command to create a home for the PhotoMap executable and library files: +In a command line window, enter the PhotoMapAI folder and run the `pip` (Python package installer) command to create a home for the PhotoMapAI executable and library files: ```bash -cd ~/PhotoMap +cd ~/PhotoMapAI pip -mvenv install --prompt photomap ``` @@ -95,17 +95,17 @@ source install/bin/activate Your system prompt should change to read `(photomap)` at this point. -### 3. Install PhotoMap and its libraries: +### 3. Install PhotoMapAI and its libraries: ```bash pip install . ``` -This will download and install all the libraries that PhotoMap requires. Depending on your internet speed, this may take a while. +This will download and install all the libraries that PhotoMapAI requires. Depending on your internet speed, this may take a while. -### 4. Launch the PhotoMap application. +### 4. Launch the PhotoMapAI application. -If installation completed without errors, launch the PhotoMap server with the `start_photomap` command: +If installation completed without errors, launch the PhotoMapAI server with the `start_photomap` command: ```bash start_photomap @@ -122,14 +122,14 @@ To launch the server again, run its executable. On Windows: ```bash -C:\path\to\PhotoMap\install\scripts\start_photomap.exe +C:\path\to\PhotoMapAI\install\scripts\start_photomap.exe ``` On Linux/MacOS: ``` bash -/path/to/PhotoMap/install/bin/start_photomap +/path/to/PhotoMapAI/install/bin/start_photomap ``` You can also just use the file browser to navigate to the `start_photomap` executable and double-click it. diff --git a/docs/installation/cuda.md b/docs/installation/cuda.md index d7d91090..4833d176 100644 --- a/docs/installation/cuda.md +++ b/docs/installation/cuda.md @@ -2,7 +2,7 @@ CUDA library versions 12.6 through 12.9 are required to take advantage of GPU acceleration on NVidia graphics cards. Acceleration will dramatically speed up indexing of your photo collection by about 10X. After the index is built, GPU acceleration offers only a modest increase in performance when searching image content by text or image similarity. Note that CUDA is **not** available (or required) for MacOS systems. -CUDA version 13 is not currently supported by the AI libraries underlying PhotoMap. +CUDA version 13 is not currently supported by the AI libraries underlying PhotoMapAI. ## Steps to Install CUDA @@ -28,5 +28,5 @@ Go to the [CUDA 12.9 Download Page](https://developer.nvidia.com/cuda-12-9-0-dow In a command shell, run the `nvidia-smi` command as in (1) and confirm that the expected version is installed. -[PhotoMap Installation](../installation.md) +[PhotoMapAI Installation](../installation.md) diff --git a/docs/user-guide/albums.md b/docs/user-guide/albums.md index 61a64df8..78d7fb89 100644 --- a/docs/user-guide/albums.md +++ b/docs/user-guide/albums.md @@ -1,6 +1,6 @@ # Managing Albums -PhotoMap allows you to organize your photos and other images into a series of albums. Each album draws its images from one or more folders of images, and manages independent search indexes and semantic maps. Albums may also overlap by having some image paths in common -- with some restrictions. +PhotoMapAI allows you to organize your photos and other images into a series of albums. Each album draws its images from one or more folders of images, and manages independent search indexes and semantic maps. Albums may also overlap by having some image paths in common -- with some restrictions. ## Adding Albums @@ -17,22 +17,22 @@ The Album Management dialogue provides you with controls for creating new albums To add an album, press the green Add Album button. This will add a new section to the dialogue window that prompts you to enter the following fields: -- **Album Key** - This is a short mnemonic text that is used to uniquely identify the album. You can add it to PhotoMap's URL in order to go directly to the album of your choice, so it is best to avoid spaces and symbols. Once the key is assigned, you can't change it. +- **Album Key** - This is a short mnemonic text that is used to uniquely identify the album. You can add it to PhotoMapAI's URL in order to go directly to the album of your choice, so it is best to avoid spaces and symbols. Once the key is assigned, you can't change it. - **Display Name** - This is the name of the album that will be displayed in the settings Album popup menu and the browser tab window title. - **Description** (optional) - A description of the album. - **Image Paths** - One or more filesystem paths to the folders that contain image files to incorporate into the album. -You are free to organize your image files in any way you wish. You can dump them into a single big folder, or organize them into multiple nested subfolders. During indexing, PhotoMap will traverse the folder structure and identify all image files of type JPEG, PNG, TIFF, HEIF, and HEIC. +You are free to organize your image files in any way you wish. You can dump them into a single big folder, or organize them into multiple nested subfolders. During indexing, PhotoMapAI will traverse the folder structure and identify all image files of type JPEG, PNG, TIFF, HEIF, and HEIC. ## Indexing Albums -For fast search and retrieval, PhotoMap indexes all the image files it finds and stores them in a compact set of indexes. Indexing begins automatically when you first add an album, and will continue in the background even if you navigate away from the Album Manager, or even close the browser. +For fast search and retrieval, PhotoMapAI indexes all the image files it finds and stores them in a compact set of indexes. Indexing begins automatically when you first add an album, and will continue in the background even if you navigate away from the Album Manager, or even close the browser. The time it takes to index depends on how many image files you have, their size, the speed of the disk media, and the availability of a GPU. On a typical Windows machine with an NVidia graphics card, it takes ~2 hours to index 80,000 images located on a network mounted disk. Expect the speed to be noticeably faster on a collection of images located on a local solid-state disk, and much slower (about 10X) on a machine that lacks GPU acceleration. -During indexing, PhotoMap will display its progress in three phases. First, it traverses the directory(ies) specified in the album configuration to identify and count image files. During this time PhotoMap displays the number of images it has found, but is unable to provide a time or %completion estimate. Second, it runs each image through a machine learning (AI) model to extract high-dimensional semantic information from the image (technically an "embedding"). During this phase, which is usually the longest in duration, PhotoMap will display its progress towards completion and an ETA. Lastly, PhotoMap generates the cluster map for all the image embeddings it has generated (technically, this is called a "umap"). The umap creation phase typically takes less than a minute and does not benefit from GPU acceleration. +During indexing, PhotoMapAI will display its progress in three phases. First, it traverses the directory(ies) specified in the album configuration to identify and count image files. During this time PhotoMapAI displays the number of images it has found, but is unable to provide a time or %completion estimate. Second, it runs each image through a machine learning (AI) model to extract high-dimensional semantic information from the image (technically an "embedding"). During this phase, which is usually the longest in duration, PhotoMapAI will display its progress towards completion and an ETA. Lastly, PhotoMapAI generates the cluster map for all the image embeddings it has generated (technically, this is called a "umap"). The umap creation phase typically takes less than a minute and does not benefit from GPU acceleration. When the indexing process is done, you will find the generated indexes stored in a folder named "photomap_index" located in the first image folder path of the album. Try not to remove or rename this folder. The indexes are relatively small. A folder of 80,000 images that totals 85 GB yields an index that is 300 MB in size. @@ -44,7 +44,7 @@ To make changes to an album's definition, including changing its display name, d ## Deleting an Album -To delete an album, click on the red Delete button next to the album entry. This will delete the configuration for the album, but doesn't change the underlying image files or the PhotoMap indexes. In particular, if you now add a new album that contains the same image path(s) as the previously-deleted album, the leftover indexes will be recognized and valid and you will not need to reindex. +To delete an album, click on the red Delete button next to the album entry. This will delete the configuration for the album, but doesn't change the underlying image files or the PhotoMapAI indexes. In particular, if you now add a new album that contains the same image path(s) as the previously-deleted album, the leftover indexes will be recognized and valid and you will not need to reindex. ## Selecting an Album by URL diff --git a/docs/user-guide/basic-usage.md b/docs/user-guide/basic-usage.md index 3e55cce6..516c96d4 100644 --- a/docs/user-guide/basic-usage.md +++ b/docs/user-guide/basic-usage.md @@ -1,10 +1,10 @@ # Basic Usage -PhotoMap is organized into a series of photo albums. Each album is a collection of images on the local machine or a shared drive. +PhotoMapAI is organized into a series of photo albums. Each album is a collection of images on the local machine or a shared drive. ## Creating an album -The first time you launch PhotoMap it will prompt you to create an album with the screen shown below. +The first time you launch PhotoMapAI it will prompt you to create an album with the screen shown below. Album creation dialogue @@ -12,7 +12,7 @@ Enter a short lowercase key for the album, such as "family", a longer descriptiv You'll now need to tell the album where its photos are stored. Enter one or more filesystem paths in the text field at the bottom named "Image Paths". Photos can be stored in a single large folder, or stored in multiple nestered folders. They can reside on the local disk or on a shared disk. If you wish, you can point the album to multiple folders, and their contents will be combined into a single album. -PhotoMap supports photos in JPEG, PNG, TIFF, and HEIC/HEIF formats. +PhotoMapAI supports photos in JPEG, PNG, TIFF, and HEIC/HEIF formats. The screenshot below shows the dialogue after populating it on a Linux or MacOS system. On Windows systems use the usual `C:\path\to\directory` notation. @@ -22,7 +22,7 @@ Once the album is set up to your liking, press the `Add Album` button at the bot Album indexing -Indexing can take some time. On a system equipped with an NVidia GPU, indexing a collection of ~50,000 images will take about two hours. On a system with CPU only, the process will take overnight. Mac users with hardware accelerated M1/2/3 chips will see performance somewhere in between the two. It is suggested to start with a small collection of photos (1000-2000 images) for your first album in order to test PhotoMap and get comfortable with its features. +Indexing can take some time. On a system equipped with an NVidia GPU, indexing a collection of ~50,000 images will take about two hours. On a system with CPU only, the process will take overnight. Mac users with hardware accelerated M1/2/3 chips will see performance somewhere in between the two. It is suggested to start with a small collection of photos (1000-2000 images) for your first album in order to test PhotoMapAI and get comfortable with its features. Once indexing is complete, the dialogue will close and you can start exploring your collection. @@ -40,9 +40,9 @@ The album browsing interface is shown below. Hover over the image to see the key Going from left to right: - The *Next Image* and *Previous Image* buttons advance to the next or previous photographs in the album. -- The *Gear* button opens up a dialogue that lets you adjust the behavior and appearance of PhotoMap. +- The *Gear* button opens up a dialogue that lets you adjust the behavior and appearance of PhotoMapAI. - The *Trash* icon permanently deletes the current photo from the album and removes the disk file (after confirmation). -- The *Fullscreen* button puts PhotoMap into fullscreen mode and hides most of the control elements. +- The *Fullscreen* button puts PhotoMapAI into fullscreen mode and hides most of the control elements. - The *Play/Pause* button starts and stops a slideshow in which the photos autoadvance after a user-adjustable interval. - The *Target* icon opens and closes the [semantic map](semantic-map.md). - The *Landscape* icon initiates a search for images similar to the one currently displayed. @@ -74,13 +74,13 @@ If you hover over the top of the map, additional navigation controls appear for ## Changing Settings -The Gear icon opens the settings dialogue, which allows you to adjust the appearance and behavior of PhotoMap: +The Gear icon opens the settings dialogue, which allows you to adjust the appearance and behavior of PhotoMapAI: -PhotoMap Settings Dialogue +PhotoMapAI Settings Dialogue - **Image Change Interval** -- When the slideshow is running, this controls how long each image will be displayed, in seconds. - **Image Browse Order** -- When the slideshow is running, or when you are browsing the album without an active search, this controls the order in which photos are displayed. "Random" will present the images in shuffled order, while "Chronological" will show them in order from oldest to newest. -- **Max Images in History** -- PhotoMap keeps a small number of recently-viewed photos in memory. The others are swapped in and out to disk. This value controls how many images are kept in memory at once. Reduce the size if you are having memory problems or the application seems to be slowing down. -- **LocationIQ Map API Key** -- This optional API key lets PhotoMap display thumbnail maps and named locations for photos that contain GPS geolocation information. If you wish to enable this feature, get a key for free from [LocationIQ](http://locationiq.com/) and paste it into the field. If not present, PhotoMap will display the longitude and latitude of the photo, but not the map or place name. +- **Max Images in History** -- PhotoMapAI keeps a small number of recently-viewed photos in memory. The others are swapped in and out to disk. This value controls how many images are kept in memory at once. Reduce the size if you are having memory problems or the application seems to be slowing down. +- **LocationIQ Map API Key** -- This optional API key lets PhotoMapAI display thumbnail maps and named locations for photos that contain GPS geolocation information. If you wish to enable this feature, get a key for free from [LocationIQ](http://locationiq.com/) and paste it into the field. If not present, PhotoMapAI will display the longitude and latitude of the photo, but not the map or place name. - **Album** -- This pulldown menu lists all the albums you have configured and allows you to switch among them. Note that when you switch albums, the settings dialogue will close immediately and the window will display the first photo from the selected albums. - **Manage Albums** -- This green button will open the [Album Manager](albums.md), where you can create, edit and delete albums. diff --git a/docs/user-guide/search.md b/docs/user-guide/search.md index 50f0472c..014eac1e 100644 --- a/docs/user-guide/search.md +++ b/docs/user-guide/search.md @@ -1,19 +1,19 @@ #Search -PhotoMap provides several types of AI-enabled search across your image/photo collection: +PhotoMapAI provides several types of AI-enabled search across your image/photo collection:
Search Panel
-- **Search by Image** - Provide an image and PhotoMap will find matches against it. -- **Search by Text** - Type in a word or phrase and PhotoMap will find the closest matches. +- **Search by Image** - Provide an image and PhotoMapAI will find matches against it. +- **Search by Text** - Type in a word or phrase and PhotoMapAI will find the closest matches. - **Search by Text and Image** - Provide image and text to find matches that best combine the two. You can also provide a "negative search text" to disfavor certain image content. - **Search by Map** - Browse images that are clustered together in the [semantic map](semantic-map.md). ## Search by Image -To search PhotoMap by image similarity: +To search PhotoMapAI by image similarity: 1. Find images similar to the one currently on display in the main window. @@ -37,7 +37,7 @@ The screenshot below shows the results of an image search on a photo of a generi ## Search by Text -Open the search **By Text** magnifying glass icon and type your search term into the input field labeled "Text Search." A wide variety of search terms are accepted. You can search for people ("blonde man in wool sweater"), subjects ("birthday party"), styles ("graphic novel"), or photography-related descriptors ("out of focus", "motion blur"). You can search for certain celebrities by name, but you *cannot* search for family members, friends and other private individuals. (Providing a way to train PhotoMap with custom data is a potential future improvement.) +Open the search **By Text** magnifying glass icon and type your search term into the input field labeled "Text Search." A wide variety of search terms are accepted. You can search for people ("blonde man in wool sweater"), subjects ("birthday party"), styles ("graphic novel"), or photography-related descriptors ("out of focus", "motion blur"). You can search for certain celebrities by name, but you *cannot* search for family members, friends and other private individuals. (Providing a way to train PhotoMapAI with custom data is a potential future improvement.) ## Search by a Combination of Text and Image @@ -51,11 +51,11 @@ Clicking on the ⊙ (target) icon will open the [Semantic Map](semantic-map.md) Semantic Map -If you hover over dots adjacent to the current one, PhotoMap will pop up a thumbnail image to show you the neighbors of the current image. Clicking on a colored cluster will select all members of the cluster, dim other clusters, and set the selected cluster's members as the current search results. To turn off the cluster highlighting and restore full brightness to all clusters, uncheck the **Highlight selection** checkbox in the bottom right-hand corner. +If you hover over dots adjacent to the current one, PhotoMapAI will pop up a thumbnail image to show you the neighbors of the current image. Clicking on a colored cluster will select all members of the cluster, dim other clusters, and set the selected cluster's members as the current search results. To turn off the cluster highlighting and restore full brightness to all clusters, uncheck the **Highlight selection** checkbox in the bottom right-hand corner. ## Clearing the Search -When a search is active, a green checkmark on top of one or more search icons indicates the search type, and a clear search **X Icon** appears in the row of search icons. Click this box to clear the search results and reset PhotoMap to album browsing mode. Alternatively you can individually clear the similarity search image, and the positive and negative text search fields, by clicking on the **X** marks in their respective fields of the combined image and text search dialogue. +When a search is active, a green checkmark on top of one or more search icons indicates the search type, and a clear search **X Icon** appears in the row of search icons. Click this box to clear the search results and reset PhotoMapAI to album browsing mode. Alternatively you can individually clear the similarity search image, and the positive and negative text search fields, by clicking on the **X** marks in their respective fields of the combined image and text search dialogue.
Base image diff --git a/docs/user-guide/semantic-map.md b/docs/user-guide/semantic-map.md index f6b47236..f46afc70 100644 --- a/docs/user-guide/semantic-map.md +++ b/docs/user-guide/semantic-map.md @@ -1,6 +1,6 @@ #Semantic Map -The PhotoMap semantic map is a graphical representation of the relationships among all the photos/images in an album. Each image is represented by a dot. Images that are similar will be closer together on the map than dissimilar images. The semantic map is linked to the main image display. The location of the current image is shown on the semantic map as a yellow target icon. Clicking on an image dot anywhere in the map will bring the full-resolution photo/image into view in the main display. Hovering over an image dot will pop up a thumbnail of the image, allowing you to rapidly explore the image landscape. +The PhotoMapAI semantic map is a graphical representation of the relationships among all the photos/images in an album. Each image is represented by a dot. Images that are similar will be closer together on the map than dissimilar images. The semantic map is linked to the main image display. The location of the current image is shown on the semantic map as a yellow target icon. Clicking on an image dot anywhere in the map will bring the full-resolution photo/image into view in the main display. Hovering over an image dot will pop up a thumbnail of the image, allowing you to rapidly explore the image landscape. @@ -8,7 +8,7 @@ The PhotoMap semantic map is a graphical representation of the relationships amo The semantic map is generated in two phases. In the first phase, which is performed when the album's index is created or updated, each image is compressed into a high-dimensional representation of its contents called an "embedding." The embeddings are then projected onto a 2D X-Y plot using the [UMAP dimensionality-reduction algorithm](https://umap-learn.readthedocs.io/en/latest/how_umap_works.html). UMAP is able to preserve the topological relationships among embeddings. Two embedding points that are close together on the UMAP are more semantically similar than two that are far apart. -In the second phase, PhotoMap applies an algorithm known as DBSCAN [Density-Based Spatial Clustering of Applications with Noise](https://en.wikipedia.org/wiki/DBSCAN) to partition the map into multiple clusters of highly-related images. Each cluster is then assigned an arbitrary color for visualization. The clustering process is quick and happens automatically the first time you open the semantic map window on a particular album. +In the second phase, PhotoMapAI applies an algorithm known as DBSCAN [Density-Based Spatial Clustering of Applications with Noise](https://en.wikipedia.org/wiki/DBSCAN) to partition the map into multiple clusters of highly-related images. Each cluster is then assigned an arbitrary color for visualization. The clustering process is quick and happens automatically the first time you open the semantic map window on a particular album. ### Tuning Clusters