diff --git a/docs/source/en/_toctree.yml b/docs/source/en/_toctree.yml index aa3139e207c3f3..dcb19d673d5443 100644 --- a/docs/source/en/_toctree.yml +++ b/docs/source/en/_toctree.yml @@ -81,6 +81,8 @@ title: Image Feature Extraction - local: tasks/mask_generation title: Mask Generation + - local: tasks/keypoint_detection + title: Keypoint Detection - local: tasks/knowledge_distillation_for_image_classification title: Knowledge Distillation for Computer Vision title: Computer Vision diff --git a/docs/source/en/tasks/keypoint_detection.md b/docs/source/en/tasks/keypoint_detection.md new file mode 100644 index 00000000000000..a0ec71a5c22000 --- /dev/null +++ b/docs/source/en/tasks/keypoint_detection.md @@ -0,0 +1,154 @@ + + +# Keypoint Detection + +[[open-in-colab]] + +Keypoint detection identifies and locates specific points of interest within an image. These keypoints, also known as landmarks, represent meaningful features of objects, such as facial features or object parts. These models take an image input and return the following outputs: + +- **Keypoints and Scores**: Points of interest and their confidence scores. +- **Descriptors**: A representation of the image region surrounding each keypoint, capturing its texture, gradient, orientation and other properties. + +In this guide, we will show how to extract keypoints from images. + +For this tutorial, we will use [SuperPoint](./model_doc/superpoint.md), a foundation model for keypoint detection. + +```python +from transformers import AutoImageProcessor, SuperPointForKeypointDetection +processor = AutoImageProcessor.from_pretrained("magic-leap-community/superpoint") +model = SuperPointForKeypointDetection.from_pretrained("magic-leap-community/superpoint") +``` + +Let's test the model on the images below. + +
+ Bee + Cats +
+ + +```python +import torch +from PIL import Image +import requests +import cv2 + + +url_image_1 = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/bee.jpg" +image_1 = Image.open(requests.get(url_image_1, stream=True).raw) +url_image_2 = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/cats.png" +image_2 = Image.open(requests.get(url_image_2, stream=True).raw) + +images = [image_1, image_2] +``` + +We can now process our inputs and infer. + +```python +inputs = processor(images,return_tensors="pt").to(model.device, model.dtype) +outputs = model(**inputs) +``` + +The model output has relative keypoints, descriptors, masks and scores for each item in the batch. The mask highlights areas of the image where keypoints are present. + +```python +SuperPointKeypointDescriptionOutput(loss=None, keypoints=tensor([[[0.0437, 0.0167], + [0.0688, 0.0167], + [0.0172, 0.0188], + ..., + [0.5984, 0.9812], + [0.6953, 0.9812]]]), + scores=tensor([[0.0056, 0.0053, 0.0079, ..., 0.0125, 0.0539, 0.0377], + [0.0206, 0.0058, 0.0065, ..., 0.0000, 0.0000, 0.0000]], + grad_fn=), descriptors=tensor([[[-0.0807, 0.0114, -0.1210, ..., -0.1122, 0.0899, 0.0357], + [-0.0807, 0.0114, -0.1210, ..., -0.1122, 0.0899, 0.0357], + [-0.0807, 0.0114, -0.1210, ..., -0.1122, 0.0899, 0.0357], + ...], + grad_fn=), mask=tensor([[1, 1, 1, ..., 1, 1, 1], + [1, 1, 1, ..., 0, 0, 0]], dtype=torch.int32), hidden_states=None) +``` + +To plot actual keypoints in the image, we need to postprocess the output. To do so, we have to pass the actual image sizes to `post_process_keypoint_detection` along with outputs. + +```python +image_sizes = [(image.size[1], image.size[0]) for image in images] +outputs = processor.post_process_keypoint_detection(outputs, image_sizes) +``` + +The outputs are now a list of dictionaries where each dictionary is a processed output of keypoints, scores and descriptors. + +```python +[{'keypoints': tensor([[ 226, 57], + [ 356, 57], + [ 89, 64], + ..., + [3604, 3391]], dtype=torch.int32), + 'scores': tensor([0.0056, 0.0053, ...], grad_fn=), + 'descriptors': tensor([[-0.0807, 0.0114, -0.1210, ..., -0.1122, 0.0899, 0.0357], + [-0.0807, 0.0114, -0.1210, ..., -0.1122, 0.0899, 0.0357]], + grad_fn=)}, + {'keypoints': tensor([[ 46, 6], + [ 78, 6], + [422, 6], + [206, 404]], dtype=torch.int32), + 'scores': tensor([0.0206, 0.0058, 0.0065, 0.0053, 0.0070, ...,grad_fn=), + 'descriptors': tensor([[-0.0525, 0.0726, 0.0270, ..., 0.0389, -0.0189, -0.0211], + [-0.0525, 0.0726, 0.0270, ..., 0.0389, -0.0189, -0.0211]}] +``` + +We can use these to plot the keypoints. + +```python +import matplotlib.pyplot as plt +import torch + +for i in range(len(images)): + keypoints = outputs[i]["keypoints"] + scores = outputs[i]["scores"] + descriptors = outputs[i]["descriptors"] + keypoints = outputs[i]["keypoints"].detach().numpy() + scores = outputs[i]["scores"].detach().numpy() + image = images[i] + image_width, image_height = image.size + + plt.axis('off') + plt.imshow(image) + plt.scatter( + keypoints[:, 0], + keypoints[:, 1], + s=scores * 100, + c='cyan', + alpha=0.4 + ) + plt.show() +``` + +Below you can see the outputs. + +
+ Bee + Cats +
+