Metadata-Version: 2.4
Name: nicopal
Version: 0.3.1
Summary: Nicopal: colour palettes designed by a protanopic student.
Author-email: Nicolas Tharaud <n.tharaud6@gmail.com>
Project-URL: Homepage, https://github.com/nicolastharaud
Keywords: color,palettes,visualization,scientific,colormap
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: matplotlib
Requires-Dist: numpy
Dynamic: license-file

# Nicopal

## Contexte
Ces palettes de couleurs ont été créées par **Nicolas Tharaud** en s’inspirant de la méthode de **Fabio Crameri** [1]. Elles ont 
pour but de représenter des variables climatiques de la façon la plus juste possible sans sur ou sous interprétation visuelle. 
Une palette de couleur doit être judicieusement choisie en fonction de la variable à représenter afin que celle-ci soit 
interprétée de la même manière par chaque observateur. Les palettes de couleurs ont été créées par un daltonien 
protanope (déficience couleur rouge). Par ailleurs, le contraste de certaines palettes sera plus visible pour un daltonien 
protanope, que pour une personne possédant une vision « normale » ou bien ayant un autre type de daltonisme et inversement. 

---

# Méthodologie de validation des palettes et création d'un score de validité scientifique 

Les palettes de couleurs incluses dans **Nicopal** ont été évaluées à l’aide d’un protocole de validation perceptuelle inspiré des principes des **Scientific Colour Maps** et de la colorimétrie perceptuelle.

Les tests reposent principalement sur l’espace colorimétrique **CIELAB** et sur la métrique de différence perceptuelle **CIEDE2000 (ΔE)**, qui permet d’estimer la distance perceptuelle entre deux couleurs telle qu’elle est perçue par l’oeil humain.

Différentes procédures de validation sont appliquées selon le type de palette :

- **Palettes séquentielles**
- **Palettes divergentes**
- **Palettes hybrides**

L’objectif est de proposer des palettes qui soient :

- perceptuellement cohérentes
- lisibles pour la visualisation de données
- robustes face aux différents types de daltonismes

---

## Validation des palettes séquentielles

### Test de monotonie de la luminosité (L*)

La composante **L\*** de l’espace CIELAB représente la luminosité perceptuelle (0 = noir, 100 = blanc).

Pour une palette séquentielle correcte, la luminosité doit évoluer de manière **monotone** le long de la palette. Cela garantit qu'une augmentation de la valeur des données correspond à une progression visuelle cohérente.

Ce test permet d’éviter les **inversions perceptuelles**, où certaines valeurs pourraient apparaître plus claires ou plus sombres que leurs voisines.

---

### Test d’uniformité perceptuelle (ΔE)

La différence perceptuelle **ΔE CIEDE2000** est calculée entre chaque paire de couleurs consécutives.

Une palette est considérée comme perceptuellement régulière lorsque les valeurs de ΔE restent relativement constantes. Cette régularité est évaluée à l’aide du **coefficient de variation** :

r = sigma_ΔE / mu_ΔE

où :

- sigma_ΔE est l'écart-type des différences perceptuelles
- mu_ΔE est leur moyenne

Un ratio faible indique des transitions de couleurs homogènes.

---

### Test de sauts perceptuels

Ce test vise à détecter des transitions trop abruptes entre deux couleurs adjacentes.

Pour cela, le **ΔE maximal** est comparé au ΔE moyen :

ΔE_max < 3 × ΔE_mean

Cette contrainte permet d’éviter l’apparition d'artefacts visuels dans la palette.

---

### Test en niveaux de gris

Les couleurs de la palette sont converties en **niveaux de gris** afin de vérifier que la progression reste perceptible sans couleur.

---

### Test de robustesse aux différents daltonismes

Afin d’évaluer l’accessibilité des palettes, des simulations de déficiences de la vision des couleurs sont réalisées pour les trois types de daltonisme :

- **Deuteranomaly**
- **Protanomaly**
- **Tritanomaly**

La régularité perceptuelle des transitions de couleurs est ensuite évaluée pour chaque simulation.

---

### Étendue perceptuelle

L’étendue perceptuelle correspond à la **distance perceptuelle cumulée ΔE** le long de la palette.

Cette valeur représente la variation perceptuelle totale de la palette. Une étendue trop faible signifie que les couleurs sont trop proches perceptuellement, tandis qu’une étendue plus large permet une meilleure discrimination des valeurs.

---

### Score Nicopal Sequential

Les résultats des différents tests sont combinés dans un **Score Nicopal Sequential**, qui regrouppe les critères suivants :

- monotonie de la luminosité L\* 
- uniformité perceptuelle ΔE
- absence de sauts perceptuels
- cohérence en niveaux de gris
- robustesse au daltonisme
- étendue perceptuelle

Le score final est normalisé sur 10 points et doit être supérieur à **8** pour que la palette séquentielle soit considérée comme valide scientifiquement.

---

## Validation des palettes divergentes

Les palettes divergentes sont utilisées pour représenter des données centrées autour d’une valeur de référence (par exemple zéro).

Leur validation inclut des contraintes supplémentaires liées à leur structure symétrique.

---

### Monotonie de la luminosité autour du centre

Une palette divergente est divisée en deux branches autour d’un **point central**.

La luminosité doit évoluer de manière monotone de part et d’autre du centre afin de préserver une progression perceptuelle cohérente.

---

### Neutralité du centre

Le centre d’une palette divergente doit être **quasi neutre**, c’est-à-dire proche du gris dans l’espace CIELAB.

La neutralité est évaluée à partir de la **chroma** :

C = sqrt(a^2 + b^2)

Une chroma faible indique une couleur proche du gris.

---

### Symétrie perceptuelle

Une palette divergente équilibrée doit présenter une **distance perceptuelle** similaire entre le centre et les deux extrémités de la palette.

Cette propriété est évaluée en comparant les distances cumulées ΔE de chaque côté du centre.

---

### Uniformité perceptuelle

La régularité des transitions est également évaluée séparément pour chaque branche de la palette afin de garantir une progression visuelle homogène.

---

### Symétrie de teinte

Les deux branches de la palette doivent idéalement correspondre à des **teintes opposées** dans l’espace colorimétrique.

Cette propriété est évaluée à partir de l’angle de teinte moyen de chaque côté de la palette.

---

### Robustesse au daltonisme

Comme pour les palettes séquentielles, des simulations de vision altérée sont réalisées afin de vérifier que la structure divergente reste perceptible.

---

### Score Nicopal Diverging

Le score global combine les critères suivants :

- monotonie de L\*
- neutralité du centre
- symétrie perceptuelle
- uniformité ΔE
- absence de sauts perceptuels
- symétrie de teinte
- robustesse au daltonisme

Le score final est normalisé sur 10 points et doit être supérieur à **7** pour que la palette divergente soit considérée comme valide scientifiquement.

---

## Validation des palettes hybrides

Les palettes hybrides combinent des propriétés **catégorielles et perceptuelles**. Elles sont généralement utilisées pour représenter un nombre limité de classes tout en conservant une cohérence visuelle.

---

### Distance perceptuelle minimale

La différence perceptuelle **ΔE CIEDE2000** est calculée entre les couleurs consécutives.

Afin de garantir une distinction visuelle suffisante entre les catégories, la condition suivante est appliquée :

ΔE ≥ 15

Ce seuil correspond à une différence perceptuelle clairement identifiable pour la plupart des observateurs.

---

### Robustesse au daltonisme

La même contrainte de séparation perceptuelle (ΔE ≥ 15) est appliquée après simulation des principales déficiences de la vision des couleurs (deuteranomaly, protanomaly, tritanomaly).

---

### Score Nicopal Hybrid

Le score final est basé sur :

- la proportion de transitions respectant la condition ΔE ≥ 15 dans la palette originale
- la même proportion évaluée après simulation de daltonisme

Le score est normalisé sur 10 points et doit être supérieur à **7** pour que la palette hybride soit considérée comme valide scientifiquement.

***************************************************************** 
#### Bibliographie : 

[1] Crameri, Fabio, Grace E. Shephard, and Philip J. Heron. 2020. ‘The Misuse of Colour in Science Communication’. 
Nature Communications 11(1): 5444. doi:10.1038/s41467-020-19160-7. 

[2] Yang, Yang, Jun Ming, and Nenghai Yu. 2012. ‘Color Image Quality Assessment Based on CIEDE2000’. Advances 
in Multimedia 2012: 1–6. doi:10.1155/2012/273723. 

**La partie _Méthodologie_ a été co-écrite avec l'agréable collaboration de ChatGPT.**
*****************************************************************

# Installation

Dans une console ou un terminal Python :

`pip install nicopal`

---

# Utilisation

### 0. Chargement du package

`import nicopal as ncp`

---

### 1. Afficher la version du package

`print(ncp.__version__)`

Affiche la version et la description complète du package.

---

### 2. Tester rapidement toutes les palettes

`print(ncp.pal_test())`

Vérifie que toutes les palettes se chargent correctement.  
Affiche un message de confirmation si tout est valide.

---

### 3. Lister les palettes disponibles

`print(ncp.pal_list())`

Affiche tous les noms de palettes disponibles dans Nicopal.

---

### 4. Visualiser une palette

`print(ncp.pal_show("Lithium"))`

Affiche un gradient de la palette choisie.
`pal_show` peut être utilisé pour toutes les palettes de `pal_list()`.

---

### 5. Visualiser toutes les palettes

`print(ncp.pal_all())`

Affiche toutes les palettes et leurs noms associés.
---

### 6. Charger une palette en liste HEX

`colors = ncp.pal_hex("Lithium")`  
`print(colors)`

Renvoie la palette en codes HEX correspondant.

---

### 7. Utiliser une palette comme colormap

`colormap   = ncp.pal("Lithium")`               
`colormap_r = ncp.pal("Lithium", reverse=True)`  

`ax.contourf(x, y, z, cmap=colormap)`

> `reverse=True` permet d’inverser la colormap.  
> `ax.contourf` peut être remplacé par toute autre fonction Matplotlib acceptant un colormap.  
> `x`, `y` et `z` sont vos données à visualiser.

---

### 8. Extraire des couleurs d'une palette

`sample = ncp.pal_sample("Carbon", 6)`
`x = ["A","B","C","D","E","F"]`
`y = [3,7,5,6,4,8]`
`plt.bar(x, y, color=sample)`
`plt.show()`

Renvoie `n` couleurs discrètes extraites de la palette.

---

### 9. Démonstration d'une palette

`print(ncp.pal_demo("Lithium")`

Affiche un exemple de visualisation utilisant la palette choisie.

---

# Nom des palettes

`Boron`     | `Carbon`   | `Chlorine` | `Cobalt`    |
`Iodine`    | `Iron`     | `Lithium`  | `Magnesium` |
`Manganese` | `Nitrogen` | `Oxygen`   | `Selenium`  |
`Silicon`   | `Sodium`   | `Sulfur`   | `Vanadium`  |

# :) NT

---
