### Install python-animeface

Source: https://github.com/nya3jp/python-animeface/blob/main/README.md

Install the python-animeface library using pip. Ensure you have the necessary build tools if a prebuilt wheel is not available for your environment.

```bash
pip install animeface
```

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

### Build libnvxs Library

Source: https://github.com/nya3jp/python-animeface/blob/main/README.md

If a prebuilt wheel is not available, you must install the libnvxs library manually. Navigate to the third-party directory, configure, build, and install the library.

```bash
cd third_party/nvxs-1.0.2
./configure
make
sudo make install
```

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

### Build animeface from source

Source: https://context7.com/nya3jp/python-animeface/llms.txt

If a pre-built wheel is not available for your platform, you can build the native dependency from source. This involves configuring and making the C library before installing the Python package.

```bash
cd third_party/nvxs-1.0.2
./configure
make
sudo make install
pip install animeface
```

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

### Access and use Face data class attributes

Source: https://context7.com/nya3jp/python-animeface/llms.txt

Demonstrates how to access detailed information about a detected face, including its bounding box, likelihood, and specific facial features like eyes, nose, and mouth. The example also shows how to crop the face region from the original image using Pillow.

```python
import animeface
import PIL.Image

im = PIL.Image.open("group_shot.png")
faces = animeface.detect(im)

face = faces[0]  # most-likely face

# likelihood: float in [0.0, 1.0] – detection confidence
assert 0.0 <= face.likelihood <= 1.0

# face.face  → BoxPart  (.pos is a Box)
# face.skin  → ColorPart (.color is a Color)
# face.hair  → ColorPart (.color is a Color)
# face.left_eye  / face.right_eye  → BoxColorPart (.pos is Box, .color is Color)
# face.mouth → BoxPart  (.pos is a Box)
# face.nose  → PointPart (.pos is a Point)
# face.chin  → PointPart (.pos is a Point)

# Crop the face region with Pillow
b = face.face.pos
cropped = im.crop((b.x, b.y, b.x + b.width, b.y + b.height))
cropped.save("face_crop.png")
```

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

### Detect Anime Faces in an Image

Source: https://github.com/nya3jp/python-animeface/blob/main/README.md

Import the animeface library and PIL.Image to open an image file. Use animeface.detect() to find faces and then access the face position and other attributes.

```python
import animeface
import PIL.Image
im = PIL.Image.open('/path/to/image.jpg')
faces = animeface.detect(im)
print(faces)
```

```python
fp = faces[0].face.pos
print(fp.x, fp.y, fp.width, fp.height)
```

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

### Handle Different Image Color Modes

Source: https://context7.com/nya3jp/python-animeface/llms.txt

Demonstrates how animeface.detect handles various PIL image modes, including RGBA, Palette, and Grayscale. It also shows error handling for unsupported modes like 32-bit float.

```python
import animeface
import PIL.Image

# RGBA PNG – converted to RGB internally
rgba_im = PIL.Image.open("sprite.png")          # mode='RGBA'
faces = animeface.detect(rgba_im)               # works fine

# Palette image – converted to RGB internally
p_im = PIL.Image.open("palette.gif")            # mode='P'
faces = animeface.detect(p_im)                  # works fine

# Grayscale – accepted as-is
gray_im = PIL.Image.open("sketch.png").convert("L")
faces = animeface.detect(gray_im)               # works fine

# 32-bit float – unsupported, raises ValueError
try:
    float_im = PIL.Image.open("hdr.tif")        # mode='F'
    animeface.detect(float_im)
except ValueError as e:
    print(f"Error: {e}")  # Unsupported color mode: F
```

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

### Detect Faces and Draw Annotations

Source: https://context7.com/nya3jp/python-animeface/llms.txt

Detect faces in an image and draw bounding boxes, nose points, chin points, and display hair color. Requires Pillow for image manipulation.

```python
import animeface
import PIL.Image
import PIL.ImageDraw

im = PIL.Image.open("anime.jpg")
faces = animeface.detect(im)

draw = PIL.ImageDraw.Draw(im)

for face in faces:
    b: animeface.Box = face.face.pos
    # Draw face bounding box
    draw.rectangle([b.x, b.y, b.x + b.width, b.y + b.height], outline="red", width=2)

    # Draw nose point
    np = face.nose.pos   # Point(x, y)
    draw.ellipse([np.x - 3, np.y - 3, np.x + 3, np.y + 3], fill="blue")

    # Draw chin point
    cp = face.chin.pos   # Point(x, y)
    draw.ellipse([cp.x - 3, cp.y - 3, cp.x + 3, cp.y + 3], fill="green")

    # Use dominant hair color to label
    hc: animeface.Color = face.hair.color
    print(f"Hair color: #{hc.r:02x}{hc.g:02x}{hc.b:02x}")

im.save("annotated.jpg")
```

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

### animeface.detect(im)

Source: https://context7.com/nya3jp/python-animeface/llms.txt

Detects anime faces in a given PIL Image object. It accepts various common color modes and returns a list of detected faces sorted by likelihood. Unsupported modes will raise a ValueError.

```APIDOC
## animeface.detect(im) — Detect anime faces in an image

### Description
Accepts a `PIL.Image.Image` object in any common color mode (`RGB`, `RGBA`, `L`, `1`, `P`, `CMYK`, `YCbCr`) and returns a `list[Face]` sorted by descending likelihood. Raises `ValueError` for unsupported modes (e.g., `I`, `F`).

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import animeface
import PIL.Image

# Load image (JPEG, PNG, WebP, etc.)
im = PIL.Image.open("anime_scene.jpg")

# Detect faces – returns [] if no face is found
faces = animeface.detect(im)

if not faces:
    print("No anime faces detected.")
else:
    for i, face in enumerate(faces):
        print(f"--- Face {i} (likelihood={face.likelihood:.4f}) ---")

        # Bounding box of the whole face region
        fb = face.face.pos          # Box(x, y, width, height)
        print(f"  Face box : x={fb.x}, y={fb.y}, w={fb.width}, h={fb.height}")

        # Dominant skin and hair colors (RGB)
        print(f"  Skin     : rgb({face.skin.color.r}, {face.skin.color.g}, {face.skin.color.b})")
        print(f"  Hair     : rgb({face.hair.color.r}, {face.hair.color.g}, {face.hair.color.b})")

        # Eye bounding boxes + dominant color
        le = face.left_eye
        print(f"  Left eye : box=({le.pos.x},{le.pos.y};{le.pos.width},{le.pos.height})" \
              f"  color=rgb({le.color.r},{le.color.g},{le.color.b})")
        re = face.right_eye
        print(f"  Right eye: box=({re.pos.x},{re.pos.y};{re.pos.width},{re.pos.height})" \
              f"  color=rgb({re.color.r},{re.color.g},{re.color.b})")

        # Mouth bounding box
        mb = face.mouth.pos
        print(f"  Mouth    : box=({mb.x},{mb.y};{mb.width},{mb.height})")

        # Nose and chin as single points
        print(f"  Nose     : ({face.nose.pos.x}, {face.nose.pos.y})")
        print(f"  Chin     : ({face.chin.pos.x}, {face.chin.pos.y})")
```

### Response
#### Success Response (200)
- **faces** (`list[Face]`) - A list of detected `Face` objects, sorted by likelihood in descending order. Returns an empty list if no faces are detected.

#### Response Example
```json
[
  {
    "likelihood": 1.0,
    "face": {"pos": {"x": 295, "y": 90, "width": 182, "height": 182}},
    "skin": {"color": {"r": 253, "g": 226, "b": 212}},
    "hair": {"color": {"r": 199, "g": 194, "b": 196}},
    "left_eye": {"pos": {"x": 408, "y": 134, "width": 34, "height": 42}, "color": {"r": 92, "g": 42, "b": 49}},
    "right_eye": {"pos": {"x": 316, "y": 137, "width": 55, "height": 48}, "color": {"r": 79, "g": 33, "b": 39}},
    "mouth": {"pos": {"x": 372, "y": 202, "width": 32, "height": 23}},
    "nose": {"pos": {"x": 397, "y": 186}},
    "chin": {"pos": {"x": 377, "y": 242}}
  }
]
```
```

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

### Face Data Class

Source: https://context7.com/nya3jp/python-animeface/llms.txt

Represents a single detected anime face, containing detailed information about its position, colors, and facial landmarks.

```APIDOC
## `Face` — Detected face data class

### Description
A `Face` instance is returned for every detected anime face. All spatial data uses image-coordinate space (origin at top-left).

### Attributes
- **likelihood** (`float`) - Detection confidence score between 0.0 and 1.0.
- **face** (`BoxPart`) - Contains the bounding box (`pos`) of the entire face region.
- **skin** (`ColorPart`) - Contains the dominant skin color (`color`) of the face.
- **hair** (`ColorPart`) - Contains the dominant hair color (`color`) of the face.
- **left_eye** (`BoxColorPart`) - Contains the bounding box (`pos`) and dominant color (`color`) of the left eye.
- **right_eye** (`BoxColorPart`) - Contains the bounding box (`pos`) and dominant color (`color`) of the right eye.
- **mouth** (`BoxPart`) - Contains the bounding box (`pos`) of the mouth region.
- **nose** (`PointPart`) - Contains the coordinates (`pos`) of the nose tip.
- **chin** (`PointPart`) - Contains the coordinates (`pos`) of the chin.

### Usage Example
```python
import animeface
import PIL.Image

im = PIL.Image.open("group_shot.png")
faces = animeface.detect(im)

face = faces[0]  # most-likely face

# likelihood: float in [0.0, 1.0] – detection confidence
assert 0.0 <= face.likelihood <= 1.0

# face.face  → BoxPart  (.pos is a Box)
# face.skin  → ColorPart (.color is a Color)
# face.hair  → ColorPart (.color is a Color)
# face.left_eye  / face.right_eye  → BoxColorPart (.pos is Box, .color is Color)
# face.mouth → BoxPart  (.pos is a Box)
# face.nose  → PointPart (.pos is a Point)
# face.chin  → PointPart (.pos is a Point)

# Crop the face region with Pillow
b = face.face.pos
cropped = im.crop((b.x, b.y, b.x + b.width, b.y + b.height))
cropped.save("face_crop.png")
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.