# Product Image Guidelines

## Purpose

Product images help users identify ammunition products while browsing, scanning, or importing catalog records.

Images are optional. RoundCount must continue working when an image is missing or unavailable.

## Supported Formats

Preferred:

- WebP

Accepted:

- JPEG
- PNG

Not accepted:

- GIF
- SVG
- TIFF
- BMP
- Renamed or executable files

## File Naming

Store images using:

    images/<manufacturer>/<product-identifier>.<extension>

Use the UPC as the filename when available:

    images/winchester/020892201989.webp

When no UPC exists, use a normalized manufacturer SKU:

    images/lake-city/lc-m193-55gr.webp

Naming requirements:

- Lowercase manufacturer directories
- Lowercase filenames
- Hyphens instead of spaces
- Letters, numbers, hyphens, and periods only

## Image Size

Recommended dimensions:

    800 x 800 pixels

Maximum dimensions:

    1600 x 1600 pixels

Recommended maximum size:

    500 KB

Absolute maximum size:

    1 MB

Images should be resized and compressed before being committed.

## Image Content

Preferred images should:

- Clearly show the product packaging
- Have a plain or uncluttered background
- Be properly oriented
- Be sharp and well lit
- Show identifying product information when possible

Do not include:

- Personal information
- People
- Receipts
- Shipping labels
- Storage locations
- Personal inventory markings
- Unrelated objects
- Contributor-added watermarks

## Catalog Record Reference

Catalog records should contain a repository-relative path:

    "image": {
      "path": "images/federal/029465063924.webp",
      "sha256": null
    }

Do not place the complete Gitea URL in each product record.

RoundCount should construct the download URL from its configured catalog repository address.

## SHA-256 Checksums

Generate a checksum with:

    sha256sum images/federal/029465063924.webp

The resulting 64-character value may be stored in the product record.

Checksums allow RoundCount to verify that the downloaded image is complete and unchanged.

## Missing Images

When no product image is available, use:

    "image": null

RoundCount should display its built-in placeholder image.

Do not store separate copies of the placeholder for every product.

## Image Validation

The catalog validation tool should eventually verify:

- The referenced image exists
- The extension is supported
- The file is a valid image
- Dimensions are within limits
- File size is within limits
- SHA-256 matches when provided
- The path remains inside the images directory

## Copyright and Sources

Only add images that may legally be stored and redistributed.

Preferred sources:

1. Original contributor photograph
2. Manufacturer-provided media
3. Distributor media with redistribution permission
4. Properly licensed third-party media

Image source information should be documented when appropriate.