### Install realutils from GitHub

Source: https://github.com/deepghs/realutils/blob/main/docs/source/tutorials/installation/index.rst

Use this command to install the newest version of realutils directly from the GitHub repository.

```shell
pip install -U git+https://github.com/deepghs/realutils@main
```

--------------------------------

### Verify realutils Installation

Source: https://github.com/deepghs/realutils/blob/main/docs/source/tutorials/installation/index.rst

Run this Python script to confirm that realutils has been installed correctly. The expected output indicates a successful installation.

```python
import realutils

print(realutils.__version__)
```

```text
0.1.0
```

--------------------------------

### Install realutils with GPU support

Source: https://github.com/deepghs/realutils/blob/main/README.md

Install the package with GPU support for higher performance if your environment has an available GPU.

```shell
pip install dghs-realutils[gpu]
```

--------------------------------

### Install realutils from PyPI

Source: https://github.com/deepghs/realutils/blob/main/docs/source/tutorials/installation/index.rst

Use this command to install the latest stable version of realutils from the Python Package Index.

```shell
pip install dghs-realutils
```

--------------------------------

### Display Environment Information

Source: https://github.com/deepghs/realutils/blob/main/docs/source/information/environment.ipynb

Use this snippet to print details about the operating system, Python version, CPU, and memory. Ensure necessary libraries like `psutil`, `cpuinfo`, and `hbutils` are installed.

```python
import os
import platform
import shutil

import cpuinfo
import psutil
from hbutils.scale import size_to_bytes_str

print('OS:', platform.platform())
print('Python:', platform.implementation(), platform.python_version())
print('CPU Brand:', cpuinfo.get_cpu_info()["brand_raw"])
print('CPU Count:', os.cpu_count())
print('CPU Freq:', psutil.cpu_freq().current, 'MHz')
print('Memory Size:', size_to_bytes_str(psutil.virtual_memory().total, precision=3))
print('Has CUDA:', 'Yes' if shutil.which('nvidia-smi') else 'No')
```

--------------------------------

### Get SigLIP Image Embeddings

Source: https://context7.com/deepghs/realutils/llms.txt

Encodes images using SigLIP models. Supports single images or batches. The default multilingual model produces 768-dimensional embeddings.

```python
from realutils.metrics.siglip import get_siglip_image_embedding

# Single image → shape (1, 768)
emb = get_siglip_image_embedding('photo.jpg')
print(emb.shape, emb.dtype)  # (1, 768), float32

# Batch → shape (N, 768)
emb = get_siglip_image_embedding(['img1.jpg', 'img2.jpg'])
print(emb.shape)  # (2, 768)
```

--------------------------------

### Get CLIP Text Embeddings

Source: https://context7.com/deepghs/realutils/llms.txt

Encodes text strings into CLIP embedding vectors. Supports single strings or batches. Embeddings match the image embedding space for cross-modal tasks.

```python
from realutils.metrics.clip import get_clip_text_embedding

# Single text → shape (1, 512)
emb = get_clip_text_embedding('a photo of a cat')
print(emb.shape, emb.dtype)  # (1, 512), float32

# Batch of texts → shape (N, 512)
emb = get_clip_text_embedding([
    'a photo of a cat',
    'a photo of a dog',
    'a photo of a human',
])
print(emb.shape)  # (3, 512)
```

--------------------------------

### Get CLIP Image Embeddings

Source: https://context7.com/deepghs/realutils/llms.txt

Encodes images into CLIP embedding vectors. Supports single images or batches. Specify a different model for different embedding dimensions.

```python
from realutils.metrics.clip import get_clip_image_embedding

# Single image → shape (1, 512)
emb = get_clip_image_embedding('photo.jpg')
print(emb.shape, emb.dtype)  # (1, 512), float32

# Batch of images → shape (N, 512)
emb = get_clip_image_embedding(['cat.jpg', 'dog.jpg', 'person.jpg'])
print(emb.shape)  # (3, 512)

# Use a different CLIP variant
emb = get_clip_image_embedding('photo.jpg', model_name='openai/clip-vit-large-patch14')
print(emb.shape)  # (1, 768)
```

--------------------------------

### Get SigLIP Text Embeddings

Source: https://context7.com/deepghs/realutils/llms.txt

Encodes text into SigLIP embedding space. The default multilingual model supports text in multiple languages, suitable for non-English queries. Supports single strings or batches.

```python
from realutils.metrics.siglip import get_siglip_text_embedding

# Multilingual support via the default model
emb = get_siglip_text_embedding('a photo of a cat')
print(emb.shape)  # (1, 768)

emb = get_siglip_text_embedding([
    'a photo of a cat',
    'a photo of 2 cats',
    'a photo of a dog',
    'a photo of a woman',
])
print(emb.shape)  # (4, 768)
```

--------------------------------

### Face Detection Visualization with `isf_faces_visualize`

Source: https://context7.com/deepghs/realutils/llms.txt

Renders bounding boxes, keypoints, and optional labels (confidence, gender, age) onto an image. Returns a PIL Image object. Allows customization of appearance and resizing for display.

```python
from realutils.face.insightface import isf_analysis_faces, isf_faces_visualize
from PIL import Image

image = Image.open('group_photo.jpg')
faces = isf_analysis_faces(image)

# Draw bounding boxes with gender/age labels
vis = isf_faces_visualize(
    image,
    faces,
    fontsize=14,
    keypoint_size=10,
    box_color='#00ff00',
    max_short_edge_size=800,   # resize for display
)
vis.save('output.jpg')
vis.show()
```

--------------------------------

### Image Classification with SigLIP

Source: https://github.com/deepghs/realutils/blob/main/README.md

Classify images using SigLIP with `classify_with_siglip`. Provide a list of image paths and a list of text prompts.

```python
from realutils.metrics.siglip import classify_with_siglip

print(classify_with_siglip(
    images=[
        'xlip/1.jpg',
        'xlip/2.jpg',
    ],
    texts=[
        'a photo of a cat',
        'a photo of 2 cats',
        'a photo of 2 dogs',
        'a photo of a woman',
    ],
))
# array([[1.3782851e-03, 2.7010253e-01, 9.7517688e-05, 3.6702781e-09],
#        [3.3248414e-06, 2.2294161e-07, 1.9753381e-09, 2.2561464e-06]],
#       dtype=float32)
```

--------------------------------

### __DESCRIPTION__

Source: https://github.com/deepghs/realutils/blob/main/docs/source/api_doc/config/meta.rst

Represents the description of the RealUtils package.

```APIDOC
## __DESCRIPTION__

### Description
Represents the description of the RealUtils package.

### Type
string
```

--------------------------------

### Face Detection with YOLO

Source: https://github.com/deepghs/realutils/blob/main/README.md

Use `detect_faces` for face detection. It requires the path to an image file.

```python
from realutils.detect import detect_faces

print(detect_faces('yolo/solo.jpg'))
# [((168, 79, 245, 199), 'face', 0.7996422052383423)]
print(detect_faces('yolo/2girls.jpg'))
# [((721, 152, 1082, 726), 'face', 0.8811314702033997), ((158, 263, 509, 714), 'face', 0.8745490908622742)]
print(detect_faces('yolo/3+cosplay.jpg'))
# [((351, 228, 410, 302), 'face', 0.8392542600631714), ((384, 63, 427, 116), 'face', 0.8173024654388428), ((195, 109, 246, 161), 'face', 0.8126493692398071)]
print(detect_faces('yolo/multiple.jpg'))
# [((1074, 732, 1258, 987), 'face', 0.8792377710342407), ((1378, 536, 1541, 716), 'face', 0.8607611656188965), ((554, 295, 759, 557), 'face', 0.8541485071182251), ((897, 315, 1068, 520), 'face', 0.8539882898330688), ((1194, 230, 1329, 403), 'face', 0.8324605226516724)]
```

--------------------------------

### Generic Object Detection with YOLO

Source: https://github.com/deepghs/realutils/blob/main/README.md

Use `detect_by_yolo` for generic object detection. It requires the path to an image file.

```python
from realutils.detect import detect_by_yolo

print(detect_by_yolo('yolo/unsplash_aJafJ0sLo6o.jpg'))
# [((450, 317, 567, 599), 'person', 0.9004617929458618)]
print(detect_by_yolo('yolo/unsplash_n4qQGOBgI7U.jpg'))
# [((73, 101, 365, 409), 'vase', 0.9098997116088867), ((441, 215, 659, 428), 'vase', 0.622944176197052), ((5, 1, 428, 377), 'potted plant', 0.5178268551826477)]
print(detect_by_yolo('yolo/unsplash_vUNQaTtZeOo.jpg'))
# [((381, 103, 676, 448), 'bird', 0.9061452150344849)]
print(detect_by_yolo('yolo/unsplash_YZOqXWF_9pk.jpg'))
# [((315, 100, 690, 532), 'horse', 0.9453459978103638), ((198, 181, 291, 256), 'horse', 0.917123556137085), ((145, 173, 180, 249), 'horse', 0.7972317337989807), ((660, 138, 701, 170), 'horse', 0.4843617379665375)]
```

--------------------------------

### Face Detection Visualization — isf_faces_visualize

Source: https://context7.com/deepghs/realutils/llms.txt

Renders bounding boxes, facial keypoints, and optional labels onto an image. Returns a PIL Image.

```APIDOC
## isf_faces_visualize

### Description
Renders bounding boxes, 5-point facial keypoints, and optional confidence/gender+age labels onto an image. Returns a PIL Image.

### Parameters
- `image` (PIL.Image.Image or str): The input image object or path.
- `faces` (list[Face]): A list of Face objects containing detection information.
- `fontsize` (int, optional): Font size for labels. Defaults to 12.
- `keypoint_size` (int, optional): Size of keypoint markers. Defaults to 5.
- `box_color` (str, optional): Color of the bounding boxes (e.g., '#00ff00'). Defaults to '#00ffff'.
- `max_short_edge_size` (int, optional): Maximum size for the shorter edge of the image after resizing for display. Defaults to None.

### Request Example
```python
from realutils.face.insightface import isf_analysis_faces, isf_faces_visualize
from PIL import Image

image = Image.open('group_photo.jpg')
faces = isf_analysis_faces(image)

# Draw bounding boxes with gender/age labels
vis = isf_faces_visualize(
    image,
    faces,
    fontsize=14,
    keypoint_size=10,
    box_color='#00ff00',
    max_short_edge_size=800,
)
vis.save('output.jpg')
vis.show()
```

### Response
- `vis` (PIL.Image.Image): A PIL Image object with the visualizations rendered on it.
```

--------------------------------

### __VERSION__

Source: https://github.com/deepghs/realutils/blob/main/docs/source/api_doc/config/meta.rst

Represents the version of the RealUtils package.

```APIDOC
## __VERSION__

### Description
Represents the version of the RealUtils package.

### Type
string
```

--------------------------------

### Image Classification with CLIP

Source: https://github.com/deepghs/realutils/blob/main/README.md

Classify images using CLIP with `classify_with_clip`. Provide a list of image paths and a list of text prompts.

```python
from realutils.metrics.clip import classify_with_clip

print(classify_with_clip(
    images=[
        'xlip/1.jpg',
        'xlip/2.jpg'
    ],
    texts=[
        'a photo of a cat',
        'a photo of a dog',
        'a photo of a human',
    ],
))
# array([[0.98039913, 0.00506729, 0.01453355],
#       [0.05586662, 0.02006196, 0.92407143]], dtype=float32)
```

--------------------------------

### Detect Faces (Real + Anime)

Source: https://context7.com/deepghs/realutils/llms.txt

Detect human faces in both real photos and anime images. Custom models and thresholds can be applied. Visualization requires imgutils.

```python
from realutils.detect import detect_faces

# Single face
print(detect_faces('solo.jpg'))
# [((157, 94, 252, 208), 'face', 0.8836570382118225)]

# Multiple faces
print(detect_faces('group.jpg'))
# [((718, 154, 1110, 728), 'face', 0.8841166496276855),
#  ((157, 275, 519, 715), 'face', 0.8668240904808044)]

# Custom model and thresholds
results = detect_faces(
    'photo.jpg',
    model_name='face_detect_v0_s_yv11',
    conf_threshold=0.3,
    iou_threshold=0.6,
)

# Visualize detected faces
from imgutils.detect import detection_visualize
from matplotlib import pyplot as plt

vis = detection_visualize('group.jpg', detect_faces('group.jpg'))
plt.imshow(vis)
plt.show()
```

--------------------------------

### __TITLE__

Source: https://github.com/deepghs/realutils/blob/main/docs/source/api_doc/config/meta.rst

Represents the title of the RealUtils package.

```APIDOC
## __TITLE__

### Description
Represents the title of the RealUtils package.

### Type
string
```

--------------------------------

### Comprehensive Face Analysis with `isf_analysis_faces`

Source: https://context7.com/deepghs/realutils/llms.txt

Performs a full InsightFace pipeline: detection, gender/age estimation, and ArcFace feature extraction. Returns a list of Face objects with all attributes populated. Can skip optional stages for faster processing.

```python
from realutils.face.insightface import isf_analysis_faces

faces = isf_analysis_faces('group_photo.jpg')

for face in faces:
    print(f"BBox: {face.bbox}")
    print(f"Confidence: {face.det_score:.3f}")
    print(f"Gender: {face.gender}, Age: {face.age}")
    print(f"Keypoints: {face.keypoints}")
    print(f"Embedding shape: {face.embedding.shape}")  # (512,)
    print()

# Skip optional stages for speed
faces = isf_analysis_faces(
    'photo.jpg',
    no_genderage=True,      # skip gender/age prediction
    no_extraction=True,     # skip embedding extraction
    det_thresh=0.6,         # stricter detection threshold
    silent=True,            # disable progress bar
)
```

--------------------------------

### Head Detection — `detect_heads`

Source: https://context7.com/deepghs/realutils/llms.txt

Detects full human heads in real photos and anime images. Useful when full-face visibility is not guaranteed.

```APIDOC
## detect_heads

### Description
Detects full human heads (including hair, hats, etc.) in real photos and anime images using models from `deepghs/real_head_detection`. Useful when full-face visibility is not guaranteed.

### Method
`detect_heads(image: ImageTyping, model_name: str = 'head_detect_v0_s_yolo', conf_threshold: float = 0.4, iou_threshold: float = 0.5) -> List[Tuple[Tuple[int, int, int, int], str, float]]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **image** (ImageTyping) - Required - The input image (file path, URL, PIL Image, or numpy array).
- **model_name** (str, optional) - Defaults to 'head_detect_v0_s_yolo'. The name of the head detection model to use.
- **conf_threshold** (float, optional) - Defaults to 0.4. The confidence threshold for detection.
- **iou_threshold** (float, optional) - Defaults to 0.5. The IoU threshold for non-maximum suppression.

### Request Example
```python
from realutils.detect import detect_heads

results = detect_heads('group.jpg')
print(results)
```

### Response
#### Success Response (200)
- **List[Tuple[Tuple[int, int, int, int], str, float]]** - A list of tuples, where each tuple contains the bounding box (x0, y0, x1, y1), the label 'head', and the confidence score.

#### Response Example
```json
[((683, 48, 1199, 754), 'head', 0.8410779237747192), ((105, 91, 570, 734), 'head', 0.8339194059371948)]
```
```

--------------------------------

### RetinaFace Detection with `isf_detect_faces`

Source: https://context7.com/deepghs/realutils/llms.txt

Detects faces using RetinaFace, returning Face objects with bounding boxes and 5-point facial keypoints. Allows specifying different models, input sizes, and detection/NMS thresholds. Results can be converted to standard detection tuples.

```python
from realutils.face.insightface import isf_detect_faces

faces = isf_detect_faces('photo.jpg')
for face in faces:
    print(f"Bbox: {face.bbox}, Score: {face.det_score:.3f}")
    print(f"Keypoints: {face.keypoints}")
    # Keypoints: [(x_eye_left, y), (x_eye_right, y), (x_nose, y), ...]

# Different model (buffalo_sc = small/compact)
faces = isf_detect_faces(
    'photo.jpg',
    model_name='buffalo_sc',
    input_size=(320, 320),
    det_thresh=0.4,
    nms_thresh=0.3,
)

# Convert to standard detection tuple for use with imgutils visualizers
det_tuples = [face.to_det_tuple() for face in faces]
# [((x0, y0, x1, y1), 'Female (Age: 25)', 0.99), ...]
```

--------------------------------

### Minimal Visualization - No Labels

Source: https://context7.com/deepghs/realutils/llms.txt

Use this function for basic visualization of detected faces without any text labels. Ensure 'isf_faces_visualize' is imported and 'image' and 'faces' are defined.

```python
vis_plain = isf_faces_visualize(image, faces, no_label=True)
```

--------------------------------

### Face Detection (real + anime) — `detect_faces`

Source: https://context7.com/deepghs/realutils/llms.txt

Detects human faces in both real photos and anime images using YOLO models. Returns bounding boxes and confidence scores for each detected face.

```APIDOC
## detect_faces

### Description
Detects human faces in both real photos and anime images using YOLO models from `deepghs/real_face_detection`. Returns bounding boxes and confidence scores for each detected face.

### Method
`detect_faces(image: ImageTyping, model_name: str = 'face_detect_v0_s_yolo', conf_threshold: float = 0.4, iou_threshold: float = 0.5) -> List[Tuple[Tuple[int, int, int, int], str, float]]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **image** (ImageTyping) - Required - The input image (file path, URL, PIL Image, or numpy array).
- **model_name** (str, optional) - Defaults to 'face_detect_v0_s_yolo'. The name of the face detection model to use.
- **conf_threshold** (float, optional) - Defaults to 0.4. The confidence threshold for detection.
- **iou_threshold** (float, optional) - Defaults to 0.5. The IoU threshold for non-maximum suppression.

### Request Example
```python
from realutils.detect import detect_faces

results = detect_faces('group.jpg')
print(results)
```

### Response
#### Success Response (200)
- **List[Tuple[Tuple[int, int, int, int], str, float]]** - A list of tuples, where each tuple contains the bounding box (x0, y0, x1, y1), the label 'face', and the confidence score.

#### Response Example
```json
[((718, 154, 1110, 728), 'face', 0.8841166496276855), ((157, 275, 519, 715), 'face', 0.8668240904808044)]
```
```

--------------------------------

### Detect Objects with YOLO

Source: https://context7.com/deepghs/realutils/llms.txt

Detect arbitrary objects in an image using YOLO models. Specify model name and thresholds for custom filtering. Visualization requires imgutils.

```python
from realutils.detect import detect_by_yolo

# Default model: yolo11s; returns List[Tuple[(x0,y0,x1,y1), str, float]]
results = detect_by_yolo('photo.jpg')
print(results)
# [((450, 317, 567, 599), 'person', 0.9004617929458618)]

# Multiple objects in one image
results = detect_by_yolo('scene.jpg')
# [((73, 101, 365, 409), 'vase', 0.9098997116088867),
#  ((441, 215, 659, 428), 'vase', 0.622944176197052),
#  ((5, 1, 428, 377), 'potted plant', 0.5178268551826477)]

# Choose a specific model and tune thresholds
results = detect_by_yolo(
    'photo.jpg',
    model_name='yolo11m',      # larger, more accurate model
    conf_threshold=0.5,        # stricter confidence filter
    iou_threshold=0.5,         # stricter NMS overlap threshold
)

# Visualize with imgutils
from imgutils.detect import detection_visualize
from matplotlib import pyplot as plt

vis = detection_visualize('photo.jpg', detect_by_yolo('photo.jpg'))
plt.imshow(vis)
plt.axis('off')
plt.show()
```

--------------------------------

### Tag Real Human Photos with get_idolsankaku_tags

Source: https://github.com/deepghs/realutils/blob/main/README.md

Use the get_idolsankaku_tags function to tag real human photos. It returns rating, general, and character tags. Ensure the image path is correct.

```python
from realutils.tagging import get_idolsankaku_tags

rating, general, character = get_idolsankaku_tags('idolsankaku/1.jpg')
print(rating)
# {'safe': 0.748395562171936, 'questionable': 0.22442740201950073, 'explicit': 0.022273868322372437}
print(general)
# {'1girl': 0.7476911544799805, 'asian': 0.3681548237800598, 'skirt': 0.8094233274459839, 'solo': 0.44033104181289673, 'blouse': 0.7909733057022095, 'pantyhose': 0.8893758654594421, 'long_hair': 0.7415428161621094, 'brown_hair': 0.4968719780445099, 'sitting': 0.49351146817207336, 'high_heels': 0.41397374868392944, 'outdoors': 0.5279690623283386, 'non_nude': 0.4075928330421448}
print(character)
# {}
```

```python
rating, general, character = get_idolsankaku_tags('idolsankaku/7.jpg')
print(rating)
# {'safe': 0.9750080704689026, 'questionable': 0.0257779061794281, 'explicit': 0.0018109679222106934}
print(general)
# {'1girl': 0.5759814381599426, 'asian': 0.46296364068984985, 'skirt': 0.9698911905288696, 'solo': 0.6263223886489868, 'female': 0.5258357524871826, 'blouse': 0.8670071959495544, 'twintails': 0.9444552659988403, 'pleated_skirt': 0.8233045935630798, 'miniskirt': 0.8354354500770569, 'long_hair': 0.8752110004425049, 'looking_at_viewer': 0.4927205741405487, 'detached_sleeves': 0.9382797479629517, 'shirt': 0.8463951945304871, 'tie': 0.8901710510253906, 'aqua_hair': 0.9376567006111145, 'armpit': 0.5968506336212158, 'arms_up': 0.9492673873901367, 'sleeveless_blouse': 0.9789504408836365, 'black_thighhighs': 0.41496211290359497, 'sleeveless': 0.9865490198135376, 'default_costume': 0.36392033100128174, 'sleeveless_shirt': 0.9865082502365112, 'very_long_hair': 0.3988983631134033}
print(character)

```

--------------------------------

### Detect Human Heads

Source: https://context7.com/deepghs/realutils/llms.txt

Detect full human heads in real photos and anime images, useful when faces are not fully visible. Returns bounding boxes and confidence scores.

```python
from realutils.detect import detect_heads

print(detect_heads('solo.jpg'))
# [((162, 47, 305, 210), 'head', 0.7701659202575684)]

print(detect_heads('group.jpg'))
# [((683,  48, 1199, 754), 'head', 0.8410779237747192),
#  ((105,  91,  570, 734), 'head', 0.8339194059371948)]
```

--------------------------------

### Person Detection — `detect_persons`

Source: https://context7.com/deepghs/realutils/llms.txt

Detects full-body persons in images using models from `deepghs/real_person_detection`. Works on both real photos and anime images.

```APIDOC
## Person Detection — `detect_persons`

### Description
Detects full-body persons in images using models from `deepghs/real_person_detection`. Works on both real photos and anime images.

### Method Signature
`detect_persons(image_path: str)`

### Parameters
#### Path Parameters
- **image_path** (str) - Required - Path to the input image file.

### Request Example
```python
from realutils.detect import detect_persons

print(detect_persons('solo.jpg'))
# Expected output format: [((x1, y1, x2, y2), 'person', confidence_score)]
```

### Response
Returns a list of tuples, where each tuple contains the bounding box coordinates, the detected class ('person'), and a confidence score.
```

--------------------------------

### __AUTHOR__

Source: https://github.com/deepghs/realutils/blob/main/docs/source/api_doc/config/meta.rst

Represents the author of the RealUtils package.

```APIDOC
## __AUTHOR__

### Description
Represents the author of the RealUtils package.

### Type
string
```

--------------------------------

### Generic Object Detection with YOLO — `detect_by_yolo`

Source: https://context7.com/deepghs/realutils/llms.txt

Detects arbitrary objects in images using official pretrained YOLO models. Returns a list of (bbox, label, confidence) tuples for every detected object class.

```APIDOC
## detect_by_yolo

### Description
Detects arbitrary objects in images using official pretrained YOLO models (YOLOv5 through YOLO12 and RT-DETR). Returns a list of `(bbox, label, confidence)` tuples for every detected object class in the COCO/Open Images vocabulary.

### Method
`detect_by_yolo(image: ImageTyping, model_name: str = 'yolo11s', conf_threshold: float = 0.25, iou_threshold: float = 0.45) -> List[Tuple[Tuple[int, int, int, int], str, float]]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **image** (ImageTyping) - Required - The input image (file path, URL, PIL Image, or numpy array).
- **model_name** (str, optional) - Defaults to 'yolo11s'. The name of the YOLO model to use.
- **conf_threshold** (float, optional) - Defaults to 0.25. The confidence threshold for detection.
- **iou_threshold** (float, optional) - Defaults to 0.45. The IoU threshold for non-maximum suppression.

### Request Example
```python
from realutils.detect import detect_by_yolo

results = detect_by_yolo('photo.jpg')
print(results)
```

### Response
#### Success Response (200)
- **List[Tuple[Tuple[int, int, int, int], str, float]]** - A list of tuples, where each tuple contains the bounding box (x0, y0, x1, y1), the detected object label, and the confidence score.

#### Response Example
```json
[((450, 317, 567, 599), 'person', 0.9004617929458618)]
```
```

--------------------------------

### Comprehensive Face Analysis — isf_analysis_faces

Source: https://context7.com/deepghs/realutils/llms.txt

Runs the full InsightFace pipeline on an image, including face detection, gender/age estimation, and feature extraction. Returns a list of Face objects with all attributes populated.

```APIDOC
## isf_analysis_faces

### Description
Runs the full InsightFace pipeline on an image: RetinaFace detection → gender/age estimation → ArcFace feature extraction. Returns a list of `Face` dataclass objects with all attributes populated.

### Parameters
- `image_path` (str): Path to the input image.
- `no_genderage` (bool, optional): Skip gender/age prediction. Defaults to False.
- `no_extraction` (bool, optional): Skip embedding extraction. Defaults to False.
- `det_thresh` (float, optional): Detection threshold. Defaults to 0.5.
- `silent` (bool, optional): Disable progress bar. Defaults to False.

### Request Example
```python
from realutils.face.insightface import isf_analysis_faces

faces = isf_analysis_faces('group_photo.jpg')

for face in faces:
    print(f"BBox: {face.bbox}")
    print(f"Confidence: {face.det_score:.3f}")
    print(f"Gender: {face.gender}, Age: {face.age}")
    print(f"Keypoints: {face.keypoints}")
    print(f"Embedding shape: {face.embedding.shape}")  # (512,)
    print()

# Skip optional stages for speed
faces = isf_analysis_faces(
    'photo.jpg',
    no_genderage=True,
    no_extraction=True,
    det_thresh=0.6,
    silent=True,
)
```

### Response
- `faces` (list[Face]): A list of Face objects, each containing detected face attributes.
```

--------------------------------

### Detect Heads in Image

Source: https://context7.com/deepghs/realutils/llms.txt

Detects heads in an image using a specified model. Adjust `conf_threshold` to control detection sensitivity; lower values yield more detections.

```python
results = detect_heads(
    'photo.jpg',
    model_name='head_detect_v0_s_yv11',
    conf_threshold=0.3,   # default is 0.2, lower = more detections
    iou_threshold=0.7,
)
```

--------------------------------

### convert_idolsankaku_emb_to_prediction

Source: https://github.com/deepghs/realutils/blob/main/docs/source/api_doc/tagging/idolsankaku.rst

Converts IdolSankaku embeddings to predictions.

```APIDOC
## convert_idolsankaku_emb_to_prediction

### Description
Converts IdolSankaku embeddings to predictions.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
#### Success Response (200)
(Not specified in source)

#### Response Example
(Not specified in source)
```

--------------------------------

### Convert Embedding to Tags — `convert_idolsankaku_emb_to_prediction`

Source: https://context7.com/deepghs/realutils/llms.txt

Converts a previously extracted IdolSankaku embedding back to tag predictions without re-running the full model. Supports single embeddings and batches of embeddings efficiently.

```APIDOC
## Convert Embedding to Tags — `convert_idolsankaku_emb_to_prediction`

### Description
Converts a previously extracted IdolSankaku embedding back to tag predictions without re-running the full model. Supports single embeddings and batches of embeddings efficiently.

### Method Signature
`convert_idolsankaku_emb_to_prediction(embedding: Union[np.ndarray, List[np.ndarray]])`

### Parameters
#### Request Body
- **embedding** (np.ndarray or List[np.ndarray]) - Required - A single 1024-dimensional embedding or a list/batch of embeddings.

### Request Example (Single Embedding)
```python
import numpy as np
from realutils.tagging import get_idolsankaku_tags, convert_idolsankaku_emb_to_prediction

embedding = get_idolsankaku_tags('photo.jpg', fmt='embedding')  # shape: (1024,)
rating, general, character = convert_idolsankaku_emb_to_prediction(embedding)
```

### Request Example (Batch Processing)
```python
import numpy as np
from realutils.tagging import get_idolsankaku_tags, convert_idolsankaku_emb_to_prediction

embeddings = np.stack([
    get_idolsankaku_tags('img1.jpg', fmt='embedding'),
    get_idolsankaku_tags('img2.jpg', fmt='embedding'),
    get_idolsankaku_tags('img3.jpg', fmt='embedding'),
])
# embeddings.shape == (3, 1024)

results = convert_idolsankaku_emb_to_prediction(embeddings)
# results is a list of (rating, general, character) tuples
for i, (rating, general, character) in enumerate(results):
    print(f"Image {i}: rating={max(rating, key=rating.get)}")
```

### Response
- **rating** (dict) - Dictionary of safety ratings.
- **general** (dict) - Dictionary of general descriptive tags.
- **character** (dict) - Dictionary of character identity tags.
If a batch of embeddings is provided, the response is a list of these tuples.
```

--------------------------------

### detect_heads

Source: https://github.com/deepghs/realutils/blob/main/docs/source/api_doc/detect/head.rst

Detects heads using the realutils library. This function is part of the realutils.detect.head module.

```APIDOC
## detect_heads

### Description
Detects heads using the realutils library.

### Function Signature
`detect_heads()`

### Parameters
This function does not accept any parameters.

### Returns
This function returns the detected heads. The specific return type and structure depend on the internal implementation of the `realutils.detect.head` module.
```

--------------------------------

### Real Human Photo Tagger — `get_idolsankaku_tags`

Source: https://context7.com/deepghs/realutils/llms.txt

Tags real human photos using IdolSankaku tagger models. Returns dictionaries for rating, general descriptive tags, and character identity tags. Also supports extracting a feature embedding.

```APIDOC
## Real Human Photo Tagger — `get_idolsankaku_tags`

### Description
Tags real human photos using IdolSankaku tagger models (SwinV2 or EVA02-Large), inspired by WD-Tagger. Returns dictionaries for `rating`, `general` descriptive tags, and `character` identity tags. Also supports extracting a 1024-dim feature embedding.

### Method Signature
`get_idolsankaku_tags(image_path: str, model_name: str = 'SwinV2', general_mcut_enabled: bool = False, character_mcut_enabled: bool = False, general_threshold: float = 0.3, character_threshold: float = 0.3, no_underline: bool = False, drop_overlap: bool = False, fmt: str = 'tags')`

### Parameters
#### Path Parameters
- **image_path** (str) - Required - Path to the input image file.

#### Query Parameters
- **model_name** (str) - Optional - The name of the model to use ('SwinV2' or 'EVA02_Large'). Defaults to 'SwinV2'.
- **general_mcut_enabled** (bool) - Optional - Enables MCut adaptive thresholding for general tags. Defaults to False.
- **character_mcut_enabled** (bool) - Optional - Enables MCut adaptive thresholding for character tags. Defaults to False.
- **general_threshold** (float) - Optional - Threshold for general tags. Defaults to 0.3.
- **character_threshold** (float) - Optional - Threshold for character tags. Defaults to 0.3.
- **no_underline** (bool) - Optional - If True, returns tags with spaces instead of underscores (e.g., 'long hair' instead of 'long_hair'). Defaults to False.
- **drop_overlap** (bool) - Optional - If True, removes redundant overlapping tags. Defaults to False.
- **fmt** (str) - Optional - The desired output format. Can be 'tags' (default) or 'embedding'.

### Request Example (Default Tags)
```python
from realutils.tagging import get_idolsankaku_tags

rating, general, character = get_idolsankaku_tags('photo.jpg')

print(rating)
# Example: {'safe': 0.748, 'questionable': 0.224, 'explicit': 0.022}

print(general)
# Example: {'1girl': 0.747, 'skirt': 0.809, ...}

print(character)
# Example: {} or {'hatsune_miku': 0.946}
```

### Request Example (Embedding)
```python
embedding = get_idolsankaku_tags('photo.jpg', fmt='embedding')
print(embedding.shape)  # (1024,)
```

### Response
- **rating** (dict) - Dictionary of safety ratings (safe, questionable, explicit).
- **general** (dict) - Dictionary of general descriptive tags and their confidence scores.
- **character** (dict) - Dictionary of character identity tags and their confidence scores.
- **embedding** (numpy.ndarray) - A 1024-dimensional feature embedding if `fmt='embedding'` is used.
```

--------------------------------

### detect_persons

Source: https://github.com/deepghs/realutils/blob/main/docs/source/api_doc/detect/person.rst

Detects persons using the realutils library.

```APIDOC
## detect_persons

### Description
Detects persons in the provided input.

### Method
This is a function call within the realutils library.

### Parameters
This function does not explicitly list parameters in the provided documentation.

### Request Example
```python
import realutils

# Assuming 'image_data' is a variable holding image data
# or 'video_stream' is a variable holding video stream data
# The exact input format is not specified.

# Example for image data (hypothetical)
# persons = realutils.detect.person.detect_persons(image_data=image_data)

# Example for video stream (hypothetical)
# persons = realutils.detect.person.detect_persons(video_stream=video_stream)
```

### Response
#### Success Response
The function is expected to return detected persons. The exact format of the return value (e.g., list of bounding boxes, confidence scores) is not specified in the provided documentation.
```

--------------------------------

### Detect Persons in Image

Source: https://context7.com/deepghs/realutils/llms.txt

Detects full-body persons in images. This function works with both real photos and anime images. For visualization, use `imgutils.detect.detection_visualize`.

```python
from realutils.detect import detect_persons

print(detect_persons('solo.jpg'))
```

```python
print(detect_persons('crowd.jpg'))
```

```python
# Visualize
from imgutils.detect import detection_visualize
from matplotlib import pyplot as plt

vis = detection_visualize('crowd.jpg', detect_persons('crowd.jpg'))
plt.imshow(vis)
plt.show()
```

--------------------------------

### Tag Real Human Photos with IdolSankaku

Source: https://context7.com/deepghs/realutils/llms.txt

Tags real human photos using IdolSankaku models, returning rating, general, and character tags. Supports feature embedding extraction and adaptive thresholding. Use `model_name` to select SwinV2 or EVA02-Large.

```python
from realutils.tagging import get_idolsankaku_tags

# Default: returns (rating, general, character) tuple
rating, general, character = get_idolsankaku_tags('photo.jpg')
```

```python
# MCut adaptive thresholding (auto-selects best threshold)
rating, general, character = get_idolsankaku_tags(
    'photo.jpg',
    general_mcut_enabled=True,
    character_mcut_enabled=True,
)
```

```python
# Extract feature embedding for similarity search / indexing
embedding = get_idolsankaku_tags('photo.jpg', fmt='embedding')
print(embedding.shape)  # (1024,)
```

```python
# Use larger EVA02 model for higher accuracy
rating, general, character = get_idolsankaku_tags(
    'photo.jpg',
    model_name='EVA02_Large',
    general_threshold=0.4,
    character_threshold=0.9,
    no_underline=True,       # return "long hair" instead of "long_hair"
    drop_overlap=True,       # remove redundant overlapping tags
)
```

--------------------------------

### isf_faces_visualize

Source: https://github.com/deepghs/realutils/blob/main/docs/source/api_doc/face/insightface.rst

Visualizes detected faces on an image.

```APIDOC
## Function: isf_faces_visualize

### Description
Draws bounding boxes and labels on an image to visualize the detected faces.

### Parameters
(No parameters explicitly documented in the source)

### Returns
(No return value explicitly documented in the source)
```

--------------------------------

### get_idolsankaku_tags

Source: https://github.com/deepghs/realutils/blob/main/docs/source/api_doc/tagging/idolsankaku.rst

Retrieves tags related to IdolSankaku.

```APIDOC
## get_idolsankaku_tags

### Description
Retrieves tags related to IdolSankaku.

### Method
(Not specified in source)

### Endpoint
(Not specified in source)

### Parameters
(Not specified in source)

### Request Example
(Not specified in source)

### Response
#### Success Response (200)
(Not specified in source)

#### Response Example
(Not specified in source)
```

--------------------------------

### Gender and Age Estimation with `isf_genderage`

Source: https://context7.com/deepghs/realutils/llms.txt

Estimates gender ('F'/'M') and age from a face. Can operate on a Face object or raw bounding box coordinates. Updates the Face object in-place if provided.

```python
from realutils.face.insightface import isf_detect_faces, isf_genderage

faces = isf_detect_faces('photo.jpg')

for face in faces:
    gender, age = isf_genderage('photo.jpg', face)
    print(f"Gender: {'Female' if gender == 'F' else 'Male'}, Age: {age}")
    # Gender: Female, Age: 27
    # face.gender and face.age are also updated in-place

# Use raw bbox coordinates
gender, age = isf_genderage('photo.jpg', face=(100.0, 50.0, 300.0, 350.0))
```

--------------------------------

### __AUTHOR_EMAIL__

Source: https://github.com/deepghs/realutils/blob/main/docs/source/api_doc/config/meta.rst

Represents the author's email address for the RealUtils package.

```APIDOC
## __AUTHOR_EMAIL__

### Description
Represents the author's email address for the RealUtils package.

### Type
string
```

--------------------------------

### Detect Real-World Faces Only

Source: https://context7.com/deepghs/realutils/llms.txt

Detect faces exclusively in real-world photographs. Use `detect_faces` for anime images. Custom models and thresholds can be applied.

```python
from realutils.detect import detect_real_faces

print(detect_real_faces('solo.jpg'))
# [((168, 79, 245, 199), 'face', 0.7996422052383423)]

print(detect_real_faces('crowd.jpg'))
# [((1074, 732, 1258, 987), 'face', 0.8792377710342407),
#  ((1378, 536, 1541, 716), 'face', 0.8607611656188965),
#  ((554,  295, 759,  557), 'face', 0.8541485071182251)]

# Use a different model variant
results = detect_real_faces(
    'photo.jpg',
    model_name='yolov11m-face',   # medium-sized model
    conf_threshold=0.4,
)
```

--------------------------------

### Real-Photo-Only Face Detection — `detect_real_faces`

Source: https://context7.com/deepghs/realutils/llms.txt

Detects faces exclusively in real-world photographs using YOLO models. Use `detect_faces` for both real and anime images.

```APIDOC
## detect_real_faces

### Description
Detects faces exclusively in real-world photographs using YOLO models from `deepghs/yolo-face`. For detecting faces in both real and anime images, use `detect_faces` instead.

### Method
`detect_real_faces(image: ImageTyping, model_name: str = 'yolov11s-face', conf_threshold: float = 0.4, iou_threshold: float = 0.5) -> List[Tuple[Tuple[int, int, int, int], str, float]]`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **image** (ImageTyping) - Required - The input image (file path, URL, PIL Image, or numpy array).
- **model_name** (str, optional) - Defaults to 'yolov11s-face'. The name of the real-face detection model to use.
- **conf_threshold** (float, optional) - Defaults to 0.4. The confidence threshold for detection.
- **iou_threshold** (float, optional) - Defaults to 0.5. The IoU threshold for non-maximum suppression.

### Request Example
```python
from realutils.detect import detect_real_faces

results = detect_real_faces('crowd.jpg')
print(results)
```

### Response
#### Success Response (200)
- **List[Tuple[Tuple[int, int, int, int], str, float]]** - A list of tuples, where each tuple contains the bounding box (x0, y0, x1, y1), the label 'face', and the confidence score.

#### Response Example
```json
[((1074, 732, 1258, 987), 'face', 0.8792377710342407), ((1378, 536, 1541, 716), 'face', 0.8607611656188965), ((554, 295, 759, 557), 'face', 0.8541485071182251)]
```
```