Update README.md

README.md

@@ -2,7 +2,6 @@
 license: cc-by-4.0
 ---
 
-
 # Empathic-Insight-Face-Large
 
 **Empathic-Insight-Face-Large** is a set of 40 emotion regression models trained on the EMoNet-FACE benchmark suite. Each model is designed to predict the intensity of a specific fine-grained emotion from facial expressions. These models are built on top of SigLIP2 image embeddings followed by MLP regression heads.
@@ -66,8 +65,7 @@ from transformers import AutoModel, AutoProcessor
 from PIL import Image
 import numpy as np
 import json
-import os # For listing model files
-from pathlib import Path
+from pathlib import Path # Used for cleaner path handling
 
 # --- 1. Define MLP Architecture (Big Model) ---
 class MLP(nn.Module):
@@ -93,7 +91,10 @@ device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
 
 # === IMPORTANT: Set this to the directory where your .pth models are downloaded ===
 # If you've cloned the repo, it might be "./" or the name of the cloned folder.
-MODEL_DIRECTORY = Path("./Empathic-Insight-Face-Large") # ADJUST THIS PATH
+# Example: MODEL_DIRECTORY = Path("./Empathic-Insight-Face-Large_cloned_repo")
+MODEL_DIRECTORY = Path(".") # Assumes models are in the current directory or a sub-directory
+# If the models are in the root of where this script runs after cloning, "." is fine.
+# If they are in a subfolder, e.g., "Empathic-Insight-Face-Large", use Path("./Empathic-Insight-Face-Large")
 # ================================================================================
 
 
@@ -110,13 +111,17 @@ if neutral_stats_path.exists():
     with open(neutral_stats_path, 'r') as f:
         neutral_stats_all = json.load(f)
 else:
-    print(f"Warning: Neutral stats file not found at {neutral_stats_path}. Mean subtraction will use 0.0.")
+    print(f"Warning: Neutral stats file not found at {neutral_stats_path}. Mean subtraction will use 0.0 for all models.")
 
 
 # Load all emotion MLP models
 emotion_mlps = {}
-print(f"Loading emotion MLP models from: {MODEL_DIRECTORY}")
-for pth_file in MODEL_DIRECTORY.glob("model_*_best.pth"):
+print(f"Loading emotion MLP models from: {MODEL_DIRECTORY.resolve()}") # .resolve() gives absolute path
+model_files_found = list(MODEL_DIRECTORY.glob("model_*_best.pth"))
+if not model_files_found:
+    print(f"Warning: No model files found in {MODEL_DIRECTORY.resolve()}. Please check the MODEL_DIRECTORY path.")
+
+for pth_file in model_files_found:
     model_key_name = pth_file.stem # e.g., "model_elation_best"
     try:
         mlp_model = MLP().to(device)
@@ -125,36 +130,40 @@ for pth_file in MODEL_DIRECTORY.glob("model_*_best.pth"):
         emotion_mlps[model_key_name] = mlp_model
         # print(f"Loaded: {model_key_name}")
     except Exception as e:
-        print(f"Error loading {model_key_name}: {e}")
+        print(f"Error loading {model_key_name} from {pth_file}: {e}")
 
 if not emotion_mlps:
-    print(f"Error: No MLP models loaded. Check MODEL_DIRECTORY: {MODEL_DIRECTORY}")
+    print(f"Error: No MLP models were successfully loaded. Check MODEL_DIRECTORY and file integrity.")
 else:
     print(f"Successfully loaded {len(emotion_mlps)} emotion MLP models.")
 
 
 # --- 3. Prepare Image and Get Embedding ---
 def normalized(a, axis=-1, order=2):
+    a = np.asarray(a) # Ensure 'a' is a numpy array
     l2 = np.atleast_1d(np.linalg.norm(a, order, axis))
     l2[l2 == 0] = 1
     return a / np.expand_dims(l2, axis)
 
 # === Replace with your actual image path ===
-# image_path = "path/to/your/image.jpg"
+# image_path_str = "path/to/your/image.jpg" 
 # try:
-#     image = Image.open(image_path).convert("RGB")
-#     inputs = siglip_processor(images=[image], return_tensors="pt").to(device)
+#     image = Image.open(image_path_str).convert("RGB")
+#     inputs = siglip_processor(images=[image], return_tensors="pt", padding="max_length", truncation=True).to(device)
 #     with torch.no_grad():
-#         image_features = siglip_model.get_image_features(**inputs)
-#     embedding_numpy_normalized = normalized(image_features.cpu().numpy())
+#         image_features = siglip_model.get_image_features(**inputs) # PyTorch tensor
+#     embedding_numpy_normalized = normalized(image_features.cpu().numpy()) # Normalize on CPU
 #     embedding_tensor = torch.from_numpy(embedding_numpy_normalized).to(device).float()
 # except FileNotFoundError:
-#     print(f"Error: Image not found at {image_path}")
+#     print(f"Error: Image not found at {image_path_str}")
 #     embedding_tensor = None # Or handle error as appropriate
+# except Exception as e:
+#     print(f"Error processing image {image_path_str}: {e}")
+#     embedding_tensor = None
 # ==========================================
 
 # --- For demonstration, let's use a random embedding if no image is processed ---
-print("\nUsing a random embedding for demonstration purposes.")
+print("\nUsing a random embedding for demonstration purposes as no image path was set.")
 embedding_tensor = torch.randn(1, 1152).to(device).float()
 # ==============================================================================
 
@@ -168,6 +177,7 @@ if embedding_tensor is not None and emotion_mlps:
             neutral_mean = neutral_stats_all.get(model_key_name, {}).get("mean", 0.0)
             mean_subtracted_score = raw_score - neutral_mean
             
+            # Derive a human-readable emotion name from the model key
             emotion_name = model_key_name.replace("model_", "").replace("_best", "").replace("_", " ").title()
             results[emotion_name] = {
                 "raw_score": raw_score,
@@ -175,63 +185,59 @@ if embedding_tensor is not None and emotion_mlps:
                 "mean_subtracted_score": mean_subtracted_score
             }
 
-    # Print results
-    print("\n--- Emotion Scores ---")
-    for emotion, scores in sorted(results.items()):
-        print(f"{emotion:<35}: Mean-Subtracted = {scores['mean_subtracted_score']:.4f} (Raw = {scores['raw_score']:.4f}, Neutral Mean = {scores['neutral_mean']:.4f})")
+    # Print results, sorted alphabetically by emotion name
+    print("\n--- Emotion Scores (Mean-Subtracted) ---")
+    # Sort items by emotion name for consistent output
+    for emotion, scores in sorted(results.items()): 
+        print(f"{emotion:<35}: {scores['mean_subtracted_score']:.4f} (Raw: {scores['raw_score']:.4f}, Neutral Mean: {scores['neutral_mean']:.4f})")
 else:
-    print("Skipping inference as either embedding tensor is None or no MLP models were loaded.")
+    print("Skipping inference as either embedding_tensor is None or no MLP models were loaded.")
 ```
+
 ## Performance on EMoNet-FACE HQ Benchmark
 
 The Empathic-Insight-Face models demonstrate strong performance, achieving near human-expert-level agreement on the EMoNet-FACE HQ benchmark.
 
-Key Metric: Weighted Kappa (κ<sub>w</sub>) Agreement with Human Annotators
-(Aggregated pairwise agreement between model predictions and individual human expert annotations on the EMoNet-FACE HQ dataset)
+**Key Metric: Weighted Kappa (κ<sub>w</sub>) Agreement with Human Annotators**
+*(Aggregated pairwise agreement between model predictions and individual human expert annotations on the EMoNet-FACE HQ dataset)*
 
-Annotator Group	Mean κ<sub>w</sub> (vs. Humans)
-Human Annotators (vs. Humans)	~0.20 - 0.26*
-Empathic-Insight-Face LARGE	~0.18
-Empathic-Insight-Face SMALL	~0.14
-Proprietary Models (e.g., HumeFace)	~0.11
-Random Baseline	~0.00
+| Annotator Group                 | Mean κ<sub>w</sub> (vs. Humans) |
+| :------------------------------ | :---------------------------: |
+| Human Annotators (vs. Humans)   |        ~0.20 - 0.26*        |
+| **Empathic-Insight-Face LARGE** |          **~0.18**          |
+| Empathic-Insight-Face SMALL   |          ~0.14              |
+| Proprietary Models (e.g., HumeFace) |        ~0.11              |
+| Random Baseline                 |        ~0.00              |
 
-Human inter-annotator agreement (pairwise κ<sub>w</sub>) varies per annotator; this is an approximate range from Table 6 in the paper.
+*\*Human inter-annotator agreement (pairwise κ<sub>w</sub>) varies per annotator; this is an approximate range from Table 6 in the paper.*
 
-Interpretation (from paper Figure 3 & Table 6):
+**Interpretation (from paper Figure 3 & Table 6):**
 
-Empathic-Insight-Face LARGE (our big models) achieves agreement scores that are statistically very close to human inter-annotator agreement and significantly outperforms other evaluated systems like proprietary models and general-purpose VLMs on this benchmark.
-
-The performance indicates that with focused dataset construction and careful fine-tuning, specialized models can approach human-level reliability on synthetic facial emotion recognition tasks for fine-grained emotions.
+*   **Empathic-Insight-Face LARGE** (our big models) achieves agreement scores that are statistically very close to human inter-annotator agreement and significantly outperforms other evaluated systems like proprietary models and general-purpose VLMs on this benchmark.
+*   The performance indicates that with focused dataset construction and careful fine-tuning, specialized models can approach human-level reliability on synthetic facial emotion recognition tasks for fine-grained emotions.
 
 For more detailed benchmark results, including per-emotion performance and comparisons with other models using Spearman's Rho, please refer to the full EMoNet-FACE paper (Figures 3, 4, 9 and Table 6 in particular).
 
 ## Taxonomy
 
 The 40 emotion categories are:
-Affection, Amusement, Anger, Astonishment/Surprise, Awe, Bitterness, Concentration, Confusion, Contemplation, Contempt, Contentment, Disappointment, Disgust, Distress, Doubt, Elation, Embarrassment, Emotional Numbness, Fatigue/Exhaustion, Fear, Helplessness, Hope/Enthusiasm/Optimism, Impatience and Irritability, Infatuation, Interest, Intoxication/Altered States of Consciousness, Jealousy & Envy, Longing, Malevolence/Malice, Pain, Pleasure/Ecstasy, Pride, Relief, Sadness, Sexual Lust, Shame, Sourness, Teasing, Thankfulness/Gratitude, Triumph.
+*Affection, Amusement, Anger, Astonishment/Surprise, Awe, Bitterness, Concentration, Confusion, Contemplation, Contempt, Contentment, Disappointment, Disgust, Distress, Doubt, Elation, Embarrassment, Emotional Numbness, Fatigue/Exhaustion, Fear, Helplessness, Hope/Enthusiasm/Optimism, Impatience and Irritability, Infatuation, Interest, Intoxication/Altered States of Consciousness, Jealousy & Envy, Longing, Malevolence/Malice, Pain, Pleasure/Ecstasy, Pride, Relief, Sadness, Sexual Lust, Shame, Sourness, Teasing, Thankfulness/Gratitude, Triumph.*
 
-(See Table 4 in the paper for associated descriptive words for each category).
+*(See Table 4 in the paper for associated descriptive words for each category).*
 
 ## Limitations
 
-Synthetic Data: Models are trained on synthetic faces. Generalization to real-world, diverse, in-the-wild images is not guaranteed and requires further investigation.
-
-Static Faces: Analysis is restricted to static facial expressions, without broader contextual or multimodal cues.
-
-Cultural Universality: The 40-category taxonomy, while expert-validated, is one perspective; its universality across cultures is an open research question.
-
-Subjectivity: Emotion perception is inherently subjective.
+*   **Synthetic Data:** Models are trained on synthetic faces. Generalization to real-world, diverse, in-the-wild images is not guaranteed and requires further investigation.
+*   **Static Faces:** Analysis is restricted to static facial expressions, without broader contextual or multimodal cues.
+*   **Cultural Universality:** The 40-category taxonomy, while expert-validated, is one perspective; its universality across cultures is an open research question.
+*   **Subjectivity:** Emotion perception is inherently subjective.
 
 ## Ethical Considerations
 
 The EMoNet-FACE suite was developed with ethical considerations in mind, including:
-
-Mitigating Bias: Efforts were made to create demographically diverse synthetic datasets and prompts were manually filtered.
-
-No PII: All images are synthetic, and no personally identifiable information was used.
-
-Responsible Use: These models are released for research. Users are urged to consider the ethical implications of their applications and avoid misuse, such as for emotional manipulation or in ways that could lead to unfair or harmful outcomes.
+*   **Mitigating Bias:** Efforts were made to create demographically diverse synthetic datasets and prompts were manually filtered.
+*   **No PII:** All images are synthetic, and no personally identifiable information was used.
+*   **Responsible Use:** These models are released for research. Users are urged to consider the ethical implications of their applications and avoid misuse, such as for emotional manipulation or in ways that could lead to unfair or harmful outcomes.
 
 Please refer to the "Ethical Considerations" and "Data Integrity, Safety, and Fairness" sections in the EMoNet-FACE paper for a comprehensive discussion.
 
@@ -239,10 +245,11 @@ Please refer to the "Ethical Considerations" and "Data Integrity, Safety, and Fa
 
 If you use these models or the EMoNet-FACE benchmark in your research, please cite the original paper:
 
+```bibtex
 @inproceedings{schuhmann2025emonetface,
   title={{EMONET-FACE: An Expert-Annotated Benchmark for Synthetic Emotion Recognition}},
   author={Schuhmann, Christoph and Kaczmarczyk, Robert and Rabby, Gollam and Kraus, Maurice and Friedrich, Felix and Nguyen, Huu and Kalyan, Krishna and Nadi, Kourosh and Kersting, Kristian and Auer, Sören},
   booktitle={Conference on Neural Information Processing Systems (NeurIPS) Track on Datasets and Benchmarks},
   year={2025} % Or actual year of publication
   % TODO: Add URL/DOI when available
-}
+}