---

name: cnn description: "Find duplicate images with CNN encodings, pretrained backbones, or custom PyTorch models in imagededup." metadata: disco-role: operating disable-model-invocation: true license: Apache 2.0

cnn

Use this sub-skill when the user wants CNN-based encodings, cosine-similarity duplicate search, pretrained backbones, or custom PyTorch models.

Best-fit tasks

• Encode one image or a directory with CNN.
• Find duplicates from CNN feature vectors.
• Use a pretrained MobilenetV3, ViT, or EfficientNet wrapper.
• Build a CustomModel around a user-defined PyTorch module.
• Understand CUDA-versus-CPU behavior for the CNN workflow.

Read this sub-skill first when the request mentions

• CNN
• CustomModel
• MobilenetV3, ViT, or EfficientNet
• torch or torchvision
• cosine similarity
• min_similarity_threshold
• pretrained weights or model configuration
• custom feature extractors

Workflow overview

1. Decide whether the user wants the default pretrained model or a custom model.
2. Make sure the model returns a feature tensor with shape (batch, features).
3. Encode either a single image or a directory.
4. Search duplicates from the encoding map or directly from the directory.
5. If the user wants a removal list, convert the duplicate map to filenames to remove.

Common decisions

• Use CNN() when the user wants the default MobileNetV3-based workflow.
• Use CustomModel when the user wants to plug in a different PyTorch model.
• Use encode_image for one file or numpy array.
• Use encode_images for a directory.
• Use find_duplicates when the user needs the full duplicate map.
• Use find_duplicates_to_remove when the user wants a heuristic removal list.

Helpful facts

• CNN uses CUDA automatically when available and otherwise uses CPU.
• The default backbone is MobilenetV3.
• Pretrained wrappers for ViT and EfficientNet are also bundled.
• scores=True returns cosine similarities.
• min_similarity_threshold is a float in [-1.0, 1.0].
• num_enc_workers only parallelizes encoding on Linux.
• find_duplicates can accept either image_dir or encoding_map.

Model contract

A custom model should:

• be a PyTorch module or call-compatible object
• accept the transform output
• return a tensor whose last dimension is the feature dimension
• be paired with a transform that matches the model's preprocessing needs

The bundled pretrained wrappers already provide matching transforms and names.

GPU and CPU notes

• The CNN path is the only part of this repo that can benefit from CUDA.
• CPU fallback is supported, so CUDA is optional rather than required.
• If a GPU is available, CNN() should report cuda as its device.
• First use of the default pretrained backbone may download weights if they are not cached.

Troubleshooting pointer

Read references/troubleshooting.md for model-config validation, threshold errors, worker-count warnings, CUDA selection, and weight-download issues.

Script helper

Run scripts/cnn_smoke.py to exercise a synthetic CNN workflow with either a lightweight custom model or the pretrained default path.

When to escalate elsewhere

• If the task is only about hash methods, switch to the hashing sub-skill.
• If the task is about scoring or plotting a retrieved duplicate map, switch to the evaluation sub-skill.

Good output expectations

A good CNN-oriented answer should usually include:

• the model choice
• whether the workflow is pretrained or custom
• the expected feature shape or score behavior
• the device behavior on the current host
• any weight-download or worker-count caveat that applies