# Object Thumbnails

In SkyPortal, we provide thumbnails for objects, that are displayed on many of the frontend's pages: source page, sources list, candidates page, etc.

Some of thumbnails are generated by the backend and stored in the database when new objects are created, extracted from the images of 3 surveys: SDSS, PanSTARRS, and Legacy Survey (LS). For these, no image data is saved but only links to their thumbnail services, which return PNGs that the frontend can render and that can be cached on the client-side. A micro-service is dedicated to thumbnail generation, so that it can happen asynchronously and not block the creation of new objects.

Also, custom thumbnails can be uploaded by users, with the following types: `new`, `ref`, `sub`. These have be designed with large survey alert streams in mind, which usually rely on image difference algorithms to detect candidates, hence the triplet of new image, reference image, and subtracted image types. However, any image can be uploaded as a custom thumbnail (we recommend using the `new` type for that). To upload your own thumbnails to SkyPortal, you can use the `POST /api/thumbnails` endpoint, as described in the [API documentation](api.html#tag/thumbnails/POST/api/thumbnail). Here, we do not store URLs to any external services, but the actual image data on disk (in the `persistentdata` directory) and pointers to these files in the database.

## Updating existing thumbnails

Every now and then, the surveys mentioned above publish new data releases and/or services to fetch thumbnails from them. When that happens, SkyPortal is usually updated to start using these for new thumbnails. The URLs of existing thumbnails in the DB are still valid (unless of course, the URLs they point to aren't accessible anymore), but one may want to update them to the new ones. In that case, we provide scripts to update the content of the thumbnails table in the DB, which are found in `tools/thumbnails_udpate/`. The naming scheme of each script should be self-explanatory, and all they need as a parameter (optional) is the path to the config file with `--config=path/to/config` (default is `config.yaml` in the root of the repo).

For example, on 2025-05-03, we updated SkyPortal to start pointing to Legacy Survey's DR10 instead of DR9, and the script to update the thumbnails table is `tools/thumbnails_update/ls_dr9_to_dr10.py`. To run it, one would do:

```bash
source .venv/bin/activate
PYTHONPATH=. python tools/thumbnails_update/ls_dr9_to_dr10.py --config=config.yaml
```

Alternatively, since the thumbnail generation is handled by a micro-service which scans for objects that don't have thumbnails for all 3 surveys, a "brute-force" way to update all existing thumbnails is to delete the existing ones from the DB. **This is not recommended at all for databases with >10k objects**, but for smaller ones, it can be done by running the following queries in the DB:

```sql
BEGIN;
DELETE FROM thumbnails WHERE type in ('sdss', 'ps1', 'ls', 'dr8');
COMMIT;
```

This will delete all thumbnails of the 3 surveys, and the micro-service will then generate new ones for all the objects.