pos_face_recognition/README.md

# POS Face Recognition

## Overview

This Odoo module extends the Point of Sale (POS) system with AI-powered face recognition capabilities. It enables automatic customer identification through facial recognition, providing staff with instant access to customer information, purchase history, and personalized recommendations.

## Features

### 🎯 Core Functionality

- **Real-time Face Recognition**: Automatically identifies customers using webcam in the POS interface
- **Customer Training**: Capture and store up to 3 face images per customer for accurate recognition
- **Automatic Sync**: Face images are automatically synchronized with the AI server
- **Confidence Scoring**: Displays match probability for each recognized customer

### 📊 Customer Insights

When a customer is recognized, the sidebar displays:

- **Customer Information**: Name and contact details
- **Last 2 Orders**: Complete order history including:
  - Order number and date
  - Total amount
  - Order status (with color-coded badges)
  - Complete product list with quantities and prices
- **Top 3 Products**: Most frequently purchased items by the customer

### 🎨 User Interface

- **Sidebar Integration**: Non-intrusive sidebar in the POS product screen
- **Live Camera Feed**: Real-time video preview for face recognition
- **Match List**: Shows all potential customer matches with confidence scores
- **Detailed Order Cards**: Beautifully styled order history with hover effects
- **Responsive Design**: Optimized for POS touchscreen interfaces

## Requirements

### Odoo Dependencies

- `point_of_sale`
- `contacts`

### External Dependencies

- **AI Face Recognition Server**: A separate Python Flask server that handles face recognition
  - Repository: `ai_face_recognition_server` (included in workspace)
  - Required Python packages: `flask`, `face_recognition`, `numpy`, `opencv-python`

### Hardware Requirements

- Webcam or camera device
- Sufficient lighting for face recognition

## Installation

### 1. Install the Odoo Module

```bash
# Copy the module to your Odoo addons directory
cp -r pos_face_recognition /path/to/odoo/addons/

# Update the addons list in Odoo
# Navigate to Apps > Update Apps List

# Search for "POS Face Recognition" and install
```

### 2. Setup the AI Face Recognition Server

```bash
# Navigate to the AI server directory
cd ai_face_recognition_server

# Install Python dependencies
pip install -r requirements.txt

# Start the server
python app.py
```

The server will run on `http://localhost:5000` by default.

### 3. Configure the Module

1. Go to **Point of Sale > Configuration > Point of Sale**
2. Select your POS configuration
3. In the **Face Recognition** section, set the **Face Recognition Server URL**:
   ```
   http://localhost:5000
   ```
4. Save the configuration

## Usage

### Training Customer Faces

1. Navigate to **Contacts**
2. Open a customer record
3. In the **Face Recognition** tab, you'll find three image fields:
   - **Face Image 1**
   - **Face Image 2**
   - **Face Image 3**
4. Upload clear, front-facing photos of the customer
5. Save the record - images are automatically synced to the AI server

**Best Practices for Training Images:**
- Use well-lit, clear photos
- Capture different angles and expressions
- Ensure the face is clearly visible
- Avoid sunglasses or face coverings
- Use recent photos

### Using Face Recognition in POS

1. Open the POS session
2. The face recognition sidebar appears on the right side
3. The camera automatically starts and begins scanning for faces
4. When a customer is recognized:
   - Their name appears in the match list with a confidence score
   - Click on the match to select the customer
   - View their order history and top products
   - The customer is automatically set for the current order

### Understanding the Display

**Match List:**
- Shows all potential matches with confidence percentage
- Higher percentage = more confident match
- Click any match to select that customer

**Order History:**
- Displays the last 2 orders with complete details
- Color-coded status badges:
  - 🟢 Green: Paid/Done
  - 🔵 Blue: Invoiced
- Shows all products ordered with quantities and prices

**Top Products:**
- Highlights the 3 most frequently purchased items
- Helps staff make personalized recommendations

## Configuration

### POS Configuration

**Settings > Point of Sale > Configuration > Point of Sale**

- `pos_face_rec_server_url`: URL of the AI Face Recognition Server

### Partner Configuration

**Contacts > Customer**

- `image_face_1`: First training image
- `image_face_2`: Second training image
- `image_face_3`: Third training image

## Technical Details

### Module Structure

```
pos_face_recognition/
├── __init__.py
├── __manifest__.py
├── README.md
├── models/
│   ├── __init__.py
│   ├── pos_config.py          # POS configuration extension
│   ├── res_partner.py          # Customer model with face images
│   └── res_config_settings.py # Settings configuration
├── views/
│   ├── pos_config_views.xml
│   ├── res_partner_views.xml
│   └── res_config_settings_views.xml
└── static/
    └── src/
        ├── css/
        │   └── face_recognition.css
        ├── js/
        │   ├── face_recognition_sidebar.js
        │   ├── models.js
        │   └── partner_details_edit.js
        └── xml/
            ├── face_recognition_screens.xml
            └── partner_details_edit.xml
```

### API Endpoints

The module communicates with the AI server using these endpoints:

**POST /train**
- Trains the AI model with customer face images
- Payload: `{ partner_id, name, images: [base64_image1, base64_image2, base64_image3] }`

**POST /recognize**
- Recognizes faces in the provided image
- Payload: `{ image: base64_image }`
- Response: `{ matches: [{ id, name, probability }] }`

### Data Flow

1. **Training Phase:**
   - Customer face images uploaded in Odoo
   - Images automatically synced to AI server via `/train` endpoint
   - AI server trains face recognition model

2. **Recognition Phase:**
   - POS camera captures frames every 5 seconds
   - Frame sent to AI server via `/recognize` endpoint
   - Server returns matching customers with confidence scores
   - POS displays matches and fetches order history

### Database Schema

**res.partner (extended)**
```python
image_face_1 = fields.Binary("Face Image 1", attachment=True)
image_face_2 = fields.Binary("Face Image 2", attachment=True)
image_face_3 = fields.Binary("Face Image 3", attachment=True)
```

**pos.config (extended)**
```python
pos_face_rec_server_url = fields.Char("Face Recognition Server URL")
```

## Troubleshooting

### Camera Not Working

- **Check browser permissions**: Ensure the browser has camera access
- **HTTPS requirement**: Some browsers require HTTPS for camera access
- **Check console**: Open browser developer tools for error messages

### No Matches Found

- **Verify server connection**: Check if the AI server is running
- **Check server URL**: Ensure the URL in POS config is correct
- **Training data**: Verify customer has face images uploaded
- **Lighting**: Ensure adequate lighting for face detection

### Images Not Syncing

- **Check server URL**: Verify the Face Recognition Server URL is configured
- **Server logs**: Check AI server logs for errors
- **Network connectivity**: Ensure Odoo can reach the AI server
- **Image format**: Ensure images are in supported formats (JPEG, PNG)

### Performance Issues

- **Recognition interval**: Default is 5 seconds, can be adjusted in code
- **Image quality**: Lower resolution images process faster
- **Server resources**: Ensure AI server has adequate CPU/RAM

## Development

### Extending the Module

**Add more customer insights:**
```python
# In res_partner.py
def get_customer_stats(self):
    self.ensure_one()
    # Add custom logic
    return {...}
```

**Customize recognition interval:**
```javascript
// In face_recognition_sidebar.js
this.recognitionInterval = setInterval(() => {
    this.captureAndSendFrame();
}, 3000); // Change from 5000 to 3000 for 3 seconds
```

**Add more order history:**
```javascript
// In face_recognition_sidebar.js
const orders = await this.orm.searchRead("pos.order",
    [['partner_id', '=', partnerId]],
    ['name', 'date_order', 'amount_total', 'state', 'lines'],
    { limit: 5, order: "date_order desc" } // Change from 2 to 5
);
```

## Security & Privacy

- Face images are stored securely in Odoo's attachment system
- Communication with AI server should use HTTPS in production
- Comply with local privacy laws (GDPR, CCPA, etc.)
- Obtain customer consent before capturing face images
- Implement data retention policies
- Provide customers with opt-out options

## License

LGPL-3

## Support

For issues, questions, or contributions:
- Check the troubleshooting section
- Review server logs for detailed error messages
- Ensure all dependencies are properly installed

## Changelog

### Version 17.0.1.0.0
- Initial release
- Real-time face recognition in POS
- Customer training with 3 images
- Last 2 orders display with detailed information
- Top 3 products recommendation
- Automatic image synchronization
- Confidence scoring for matches
- Responsive sidebar UI with enhanced styling

## Credits

Developed for Odoo 17.0