hewo-face 1.0.1
A Pygame project for modular game elements with reusable objects.
License: MIT
Requires Python: >=3.10

# HeWo's Face 

HeWo Face Engine is a real-time expressive face renderer built with Pygame —
designed to bring characters like HeWo to life through geometry, emotion control, and animation.

Originally conceived as a minimalist face prototype, it has evolved into a full-featured engine
capable of handling smooth emotional transitions, blinking, talking animations, and even multimedia overlays.

The package is modular by design, making it ideal for Standalone visual experiments
or Integration into robotics pipelines (e.g., ROS 2 nodes)

It runs in real time and can be fully controlled via keyboard or HTTP API.

HeWo’s expressions are not pre-rendered: they’re algebraic. Every eye blink, mouth movement or smile
is generated by morphing geometric primitives — fast, lightweight, and customizable.

![HeWo Face](images/img.png)

## Installation

To install the package:
```bash
pip install hewo-face
````

To launch the main application:

```bash
hewo_face_main
```

---

## Controls

### Keyboard

These controls are available when running the application interactively:

| Key             | Action                                    |
| --------------- | ----------------------------------------- |
| `SPACE`         | Toggle between **increase/decrease** mode |
| `1`             | Toggle talking animation                  |
| `2`             | Trigger blink                             |
| `M`             | Set a **random** facial expression        |
| `N`             | Reset emotion to **neutral**              |
| `V`             | Increase face size                        |
| `B`             | Decrease face size                        |
| `↑` `↓` `←` `→` | Move the face up/down/left/right          |
| `Q`–`C`         | Adjust individual emotion points (mapped) |

In **adjust mode**, each key from `Q` to `C` is mapped to one facial parameter.
Pressing them will increase or decrease the corresponding value depending on the current mode (`SPACE` toggles it).

---

## API (REST)

If launched with the REST endpoint enabled, the following routes are available:

### Routes Summary

| Endpoint                       | Method | Description                          |
| ------------------------------ | ------ | ------------------------------------ |
| `/set_layout`                  | POST   | Switches current layout              |
| `/hewo/set_emotion_goal`       | POST   | Sets full emotion configuration      |
| `/hewo/adjust_emotion/<param>` | POST   | Sets value of a single face point    |
| `/hewo/get_emotion`            | GET    | Retrieves current face values        |
| `/hewo/adjust_position`        | POST   | Moves the face by (dx, dy)           |
| `/hewo/set_size`               | POST   | Sets global face size                |
| `/hewo/toggle_talk`            | POST   | Starts or stops talking animation    |
| `/hewo/trigger_blink`          | POST   | Triggers a blink                     |
| `/hewo/set_random_emotion`     | POST   | Randomizes all emotion values        |
| `/hewo/reset_emotion`          | POST   | Resets all emotion values to neutral |
| `/media/add`                   | POST   | Adds a multimedia object             |
| `/media/move`                  | POST   | Moves multimedia object              |
| `/media/set_position`          | POST   | Sets exact position of object        |
| `/media/play`                  | POST   | Starts playback                      |
| `/media/pause`                 | POST   | Pauses playback                      |
| `/media/remove`                | POST   | Removes object from layout           |

---

### Layout API

```bash
curl -X POST "$BASE_URL/set_layout" \
  -H "Content-Type: application/json" \
  -d '{"name": "hewo"}'
```

---

### 🎭 Face API

```bash
curl -X POST "$BASE_URL/hewo/set_emotion_goal" \
  -H "Content-Type: application/json" \
  -d '{"lps":100,"letl_a":0,"letl_b":0,"letl_c":0,"lebl_a":0,"lebl_b":0,"lebl_c":0,"rps":100,"retl_a":0,"retl_b":0,"retl_c":0,"rebl_a":0,"rebl_b":0,"rebl_c":0,"tl_a":0,"tl_b":0,"tl_c":0,"tl_d":0,"tl_e":0,"bl_a":0,"bl_b":0,"bl_c":0,"bl_d":0,"bl_e":0}'
```

```bash
curl -X POST "$BASE_URL/hewo/adjust_emotion/lps" \
  -H "Content-Type: application/json" \
  -d '{"value": 73}'
```

```bash
curl -X GET "$BASE_URL/hewo/get_emotion"
```

```bash
curl -X POST "$BASE_URL/hewo/adjust_position" \
  -H "Content-Type: application/json" \
  -d '{"dx": 15, "dy": -10}'
```

```bash
curl -X POST "$BASE_URL/hewo/set_size" \
  -H "Content-Type: application/json" \
  -d '{"value": 300}'
```

```bash
curl -X POST "$BASE_URL/hewo/toggle_talk"
```

```bash
curl -X POST "$BASE_URL/hewo/trigger_blink"
```

```bash
curl -X POST "$BASE_URL/hewo/set_random_emotion"
```

```bash
curl -X POST "$BASE_URL/hewo/reset_emotion"
```

---

### 🖼️ Multimedia API

```bash
curl -X POST "$BASE_URL/media/add" \
  -H "Content-Type: application/json" \
  -d '{
    "filepath": "/path/to/video.mov",
    "position": [100, 200],
    "velocity": [0, 0],
    "size": [300, 200],
    "loop": false,
    "audio": true,
    "autoplay": false,
    "name": "VideoObj1"
  }'
```

```bash
curl -X POST "$BASE_URL/media/move" \
  -H "Content-Type: application/json" \
  -d '{"name": "VideoObj1", "dx": 50, "dy": 20}'
```

```bash
curl -X POST "$BASE_URL/media/set_position" \
  -H "Content-Type: application/json" \
  -d '{"name": "VideoObj1", "x": 100, "y": 100}'
```

```bash
curl -X POST "$BASE_URL/media/play" \
  -H "Content-Type: application/json" \
  -d '{"name": "VideoObj1"}'
```

```bash
curl -X POST "$BASE_URL/media/pause" \
  -H "Content-Type: application/json" \
  -d '{"name": "VideoObj1"}'
```

```bash
curl -X POST "$BASE_URL/media/remove" \
  -H "Content-Type: application/json" \
  -d '{"name": "VideoObj1"}'
```

---

## Notes

* All routes assume the app is running at `http://127.0.0.1:8000`
* Replace `$BASE_URL` with your actual endpoint address if running remotely.
* Current layouts: `"hewo"` and `"media"` — more can be added as needed.
* Face points (`lps`, `tl_a`, `bl_c`, etc.) range from 0 to 100 and define facial expressions.