PalmSegNet

Palm Line v9 REST API

REST API service for detecting palm lines (life, heart, head, fate) using deep learning

---

📋 Table of Contents

• Overview
• Features
• Installation
• Configuration
• API Reference
• Classes & Color Codes
• Project Structure
• Troubleshooting

---

🔍 Overview

PalmSegNet provides a production-ready REST service for a deep learning model based on the UnetPlusPlus architecture, which segments four fundamental palm lines (life, heart, head, fate) at the pixel level from palm images.

The service is built on PyTorch (segmentation_models_pytorch), OpenCV, and FastAPI; providing synchronous inference, automatic hand orientation alignment, and support for multiple output formats.

---

✨ Features

⚡ Real-Time Inference	Low-latency segmentation with PyTorch-based UnetPlusPlus model
🧭 Auto Hand Side Detection	Left/right hand detection and automatic rotation/alignment (canonicalization)
📊 Detailed Analysis & Metrics	Precision scores, skeletonization, pixel counting
🎨 Multiple Output Formats	json, color_mask, overlay, labels options
🏭 Production-Ready	CORS management, environment variable-based configuration, error handling, metric logging

---

⚙️ Installation

1. Create a Virtual Environment

It is recommended to install dependencies in an isolated environment:

python -m venv venv

Windows:

venv\Scripts\activate

Linux / macOS:

source venv/bin/activate

2. Install Dependencies

pip install -r requirements.txt

💡 Note: If you are going to work in a GPU (CUDA) environment, update your PyTorch version according to the official installation guide.

3. Model Weights

Download the pre-trained model file (model_v9.pth) from the GitHub Releases page. Create a weights/ folder in the project root directory and place the downloaded file inside:

weights/
└── model_v9.pth

💡 Note: You can also use your own custom-trained model. Simply place your .pth file in the weights/ directory and update the PALM_V9_CHECKPOINT environment variable to point to your new file.

Alternatively, you can customize the file path using the PALM_V9_CHECKPOINT environment variable.

4. Start the Service

uvicorn app:app --host 0.0.0.0 --port 8000 --reload

Once the service is up, you can access the Swagger interface at: 📎 http://localhost:8000/docs

---

🛠️ Configuration

The system can be configured via an .env file or environment variables:

Variable	Default	Description
PALM_V9_CHECKPOINT	weights/model_v9.pth	Path to the .pth model file
PALM_DEVICE	cpu	Inference device (cpu / cuda)
PALM_MAX_UPLOAD_MB	20	Maximum image size that can be uploaded to the API (MB)
PALM_WARMUP	1	Pre-warms the model on startup (disable with 0)
PALM_LOG_METRICS	1	Logging of performance/latency metrics
PALM_ALLOWED_ORIGINS	*	Allowed origins for CORS (comma-separated)

Example .env file

PALM_V9_CHECKPOINT=weights/model_v9.pth
PALM_DEVICE=cuda
PALM_MAX_UPLOAD_MB=25
PALM_WARMUP=1
PALM_LOG_METRICS=1
PALM_ALLOWED_ORIGINS=http://localhost:3000,https://api.example.com

---

🚀 API Reference

GET /health

Returns service status, loaded model version, device info (CPU/CUDA), and model classes.

Example response

{
  "status": "ok",
  "model": "v9",
  "api_version": "1.1.0",
  "device": "cuda",
  "checkpoint": "model_v9.pth",
  "checkpoint_sha256": "e3b0c442...",
  "classes": {
    "0": "background",
    "1": "life",
    "2": "heart",
    "3": "head",
    "4": "fate"
  },
  "hand_side_detection": "model_based_dual_orientation"
}

---

POST /v1/predict

Processes the palm image (JPEG/PNG) and returns the segmentation results.

Query Parameters

Parameter	Type	Default	Description
output	string	overlay	Output format: overlay, color_mask, labels, json
opacity	float	0.65	Overlay opacity ratio (0.0–1.0)
hand_side	string	auto	Hand side: auto, left, right

Example Request (cURL)

curl -X POST \
  'http://127.0.0.1:8000/v1/predict?output=json&hand_side=auto' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@sample_palm.jpg;type=image/jpeg'

Example Request (Python)

import requests

url = "http://127.0.0.1:8000/v1/predict"
params = {"output": "json", "hand_side": "auto"}
files = {"file": ("sample_palm.jpg", open("sample_palm.jpg", "rb"), "image/jpeg")}

response = requests.post(url, params=params, files=files)
print(response.json())

---

🎨 Classes & Color Codes

The model detects 4 main classes excluding the background:

Class ID	Class Name	Color Code (RGB)	Preview	Description
0	background	(0, 0, 0)	⬛	Palm or background
1	life	(255, 50, 50)	🟥	Life Line
2	heart	(50, 220, 80)	🟩	Heart Line
3	head	(50, 120, 255)	🟦	Head Line
4	fate	(255, 210, 40)	🟨	Fate Line

---

📁 Project Structure

.
├── app.py                 # FastAPI entry point and endpoints
├── inference.py           # Model loading and inference (segmentation) logic
├── palm_validation.py     # Image quality and error validation
├── weights/
│   └── model_v9.pth       # Trained model weights
├── requirements.txt       # Python dependencies
├── .gitignore             # Git ignore rules
├── .env                   # Environment variables (optional)
└── README.md

---

🩺 Troubleshooting

Model file not found

Ensure that the PALM_V9_CHECKPOINT variable points to the correct path and the model_v9.pth file is located in the weights/ folder.

First request is very slow

Ensure that PALM_WARMUP=1 is set; this preloads the model into memory when the server starts.

Getting CORS error

Add your frontend's origin (e.g., http://localhost:3000) to the PALM_ALLOWED_ORIGINS variable, separated by commas.

---

Palm Line v9 — PyTorch · OpenCV · FastAPI