idf2table 0.1.8

Convertir des fichiers EnergyPlus IDF en DataFrames pandas

IDF2TABLE

Convertir des fichiers EnergyPlus IDF en DataFrames pandas

IDF2TABLE est un outil Python qui permet de convertir les objets issus de fichiers EnergyPlus IDF (Input Data File) en DataFrames pandas. Chaque ligne du DataFrame représente un objet IDF et chaque colonne représente un attribut de cet objet.

✨ Fonctionnalités

• 🔄 Conversion automatique des objets IDF en DataFrames pandas
• 📊 Support de tous les types d'objets EnergyPlus (Material, Zone, Construction, etc.)
• 🔍 Détection automatique du fichier IDD EnergyPlus
• 💾 Export des résultats en fichiers Excel
• 🎯 Interface simple et intuitive

📋 Prérequis

• Python >= 3.12
• EnergyPlus (pour le fichier IDD)
• Les autres dépendances sont installées automatiquement

🚀 Installation

📦 Dépendances

• eppy >= 0.5.66 : Manipulation des fichiers IDF EnergyPlus
• pandas >= 2.3.3 : Manipulation de DataFrames
• openpyxl >= 3.1.5 : Export Excel (inclus)

📦 Installation depuis PyPI

Une fois publié sur PyPI, vous pourrez installer le package avec :

# Installation avec uv
uv venv venv --python 3.12
source venv/bin/activate
uv pip install idf2table

Installation depuis GitLab (recommandé)

Pour installer directement depuis le dépôt GitLab :

# Avec pip
pip install git+https://gitlab.plateforme-tipee.com/idf/idf2table.git

# Avec uv
uv pip install git+https://gitlab.plateforme-tipee.com/idf/idf2table.git

Note : Si le dépôt est privé, vous devrez peut-être vous authentifier :

• Utiliser un token d'accès GitLab
• Ou utiliser : pip install git+https://<username>:<token>@gitlab.plateforme-tipee.com/idf/idf2table.git

Installation locale (mode développement)

Pour contribuer au projet ou utiliser le code local :

Mode développement (depuis le répertoire du projet) :

# Cloner le dépôt
git clone https://gitlab.plateforme-tipee.com/idf/idf2table.git
cd idf2table

# Installer en mode éditable avec uv
uv sync
# Le module est installé en mode éditable

Installation en tant que package local :

# Avec uv
uv pip install -e .

# Avec pip
pip install -e .

Dépendances

Les dépendances suivantes seront installées automatiquement :

• eppy >= 0.5.66 : Manipulation des fichiers IDF
• pandas >= 2.3.3 : DataFrames
• openpyxl >= 3.1.5 : Export Excel (inclus)

⚙️ Configuration du fichier IDD

Le fichier IDD (Input Data Dictionary) est nécessaire pour interpréter les fichiers IDF. IDF2TABLE le cherche automatiquement dans cet ordre :

1. Variable d'environnement ENERGYPLUS_IDD
2. Emplacements standards selon le système d'exploitation :
   • Windows : C:\EnergyPlusV9-4-0\Energy+.idd ou C:\Program Files\EnergyPlusV9-4-0\Energy+.idd
   • macOS : /Applications/EnergyPlus-9-4-0/Energy+.idd
   • Linux : ./EnergyPlus-9.4.0-998c4b761e-Linux-Ubuntu18.04-x86_64/Energy+.idd

Définir manuellement le chemin IDD

export ENERGYPLUS_IDD=/chemin/vers/Energy+.idd

📖 Utilisation

En tant que module Python

from idf2table import idf_to_table, find_idd
from eppy.modeleditor import IDF

# Configurer le fichier IDD
idd_path = find_idd()
IDF.setiddname(str(idd_path))

# Charger le fichier IDF
idf = IDF('data/OPIO_run.idf')

# Convertir les objets Material en DataFrame
materials_df = idf_to_table(idf, "Material")

print(materials_df.head())

Utilisation simplifiée (chemin de fichier direct)

from idf2table import idf_to_table

# Le fichier IDD sera trouvé automatiquement
materials_df = idf_to_table('data/OPIO_run.idf', "Material")

En ligne de commande (CLI)

Exporter la géométrie IDF en Wavefront OBJ

# Export des BuildingSurface:Detailed
idf2table export-obj data/OPIO_run.idf --obj out/model.obj

# Inclure fenêtres/portes et ombrages, générer un MTL et inverser les normales
idf2table export-obj data/OPIO_run.idf --obj out/model.obj \
  --with-fenestration --with-shading --mtl out/model.mtl --flip-normals

API d'export OBJ

from idf2table.obj_export import export_idf_to_obj, ObjExportOptions

opts = ObjExportOptions(include_fenestration=True, include_shading=True, write_mtl=True, mtl_path="out/model.mtl")
export_idf_to_obj("data/OPIO_run.idf", "out/model.obj", options=opts)

Une fois le module installé, vous disposez d'une commande idf2table avec des sous-commandes :

# Afficher l'aide générale
idf2table --help

# 1) Convertir un type d'objet en DataFrame (sous-commande: table)
idf2table table data/OPIO_run.idf Material

# Exporter en Excel
idf2table table data/OPIO_run.idf Material --output materials.xlsx

# Exporter en CSV
idf2table table data/OPIO_run.idf Material --csv

# Spécifier un fichier IDD personnalisé
idf2table table data/OPIO_run.idf Material --idd /path/to/Energy+.idd

# 2) Appliquer des mises à jour depuis un Excel/CSV (sous-commande: apply)
idf2table apply data/OPIO_run.idf --excel updates.xlsx --save data/OPIO_run_updated.idf

# Utiliser une feuille nommée
idf2table apply data/OPIO_run.idf --excel updates.xlsx --sheet MA_FEUILLE --save out.idf

# Exemple avec CSV
idf2table apply data/OPIO_run.idf --excel updates.csv --save out.idf

Exemples de types d'objets

from idf2table import idf_to_table

# Avec un objet IDF déjà chargé
from eppy.modeleditor import IDF
from idf2table import find_idd

idd_path = find_idd()
IDF.setiddname(str(idd_path))
idf = IDF('data/OPIO_run.idf')

# Matériaux
materials_df = idf_to_table(idf, "Material")

# Zones
zones_df = idf_to_table(idf, "Zone")

# Surfaces de bâtiment
surfaces_df = idf_to_table(idf, "BuildingSurface:Detailed")

# Constructions
constructions_df = idf_to_table(idf, "Construction")

# Propriétés HAMT (Heat And Moisture Transfer)
hamt_df = idf_to_table(idf, "MaterialProperty:HeatAndMoistureTransfer:SorptionIsotherm")

Lister tous les types d'objets disponibles

from idf2table import find_idd
from eppy.modeleditor import IDF

idd_path = find_idd()
IDF.setiddname(str(idd_path))
idf = IDF('data/OPIO_run.idf')

# Afficher tous les types d'objets disponibles
print(list(idf.idfobjects.keys()))

Export en Excel

Avec pandas :

from idf2table import idf_to_table

materials_df = idf_to_table('data/OPIO_run.idf', "Material")
materials_df.to_excel('materials.xlsx', index=False)

Ou avec la CLI :

idf2table data/OPIO_run.idf Material --output materials.xlsx

📚 API

Mise à jour IDF depuis Excel/CSV

Format attendu (tableau « large » exporté par idf_to_table)

• Colonnes obligatoires: key, Name
• Toutes les autres colonnes sont interprétées comme des champs à mettre à jour

Exemple minimal:

key	Name	Conductivity	Density
Material	MyMaterial	0.038	50
Material	AnotherMaterial	0.040	25

Notes:

• La colonne key correspond au type d’objet (ex: Material, Construction)
• La colonne Name correspond au nom d’objet IDF
• Les fichiers .csv sont également acceptés

Note: les fichiers .csv sont également acceptés (mêmes colonnes).

API Python

from idf2table import find_idd
from idf2table.core import apply_updates_from_excel
from eppy.modeleditor import IDF

idd = find_idd(); IDF.setiddname(str(idd))
idf = IDF('data/OPIO_run.idf')

# Appliquer les updates depuis Excel
idf = apply_updates_from_excel(idf, 'updates.xlsx', save_to='data/OPIO_run_updated.idf')

idf_to_table(idf, object_type, idd_file=None)

Convertit tous les objets d'un type donné en DataFrame pandas.

Paramètres :

Paramètre	Type	Description
idf	IDF ou str	Objet IDF ou chemin vers le fichier .idf
object_type	str	Type d'objet à convertir (ex: "Material", "Zone")
idd_file	str, optionnel	Chemin vers le fichier IDD. Si non fourni, recherche automatique

Retourne :

• pd.DataFrame : DataFrame où chaque ligne = un objet, chaque colonne = un attribut

Exemple de résultat :

   key              Name Roughness  Thickness  Conductivity  Density  Specific_Heat  ...
0  Material  MATERIAL_1     Rough        0.1         0.038     50.0         1540.0  ...
1  Material  MATERIAL_2     Rough       0.12           2.0   2400.0          880.0  ...

find_idd()

Trouve automatiquement le fichier IDD EnergyPlus.

Retourne :

• Path : Chemin vers le fichier IDD trouvé

Lève :

• FileNotFoundError : Si aucun fichier IDD n'est trouvé

Exemple :

from main import find_idd

try:
    idd_path = find_idd()
    print(f"IDD trouvé : {idd_path}")
except FileNotFoundError as e:
    print(f"Erreur : {e}")

Interface en ligne de commande

Après installation, utilisez la commande idf2table :

idf2table <idf_file> <object_type> [options]

Options :

Option	Description
--idd IDD	Chemin vers le fichier IDD (optionnel)
--output OUTPUT, -o OUTPUT	Chemin de sortie pour le fichier Excel (optionnel)
--csv	Sauvegarder en CSV au lieu d'Excel

Exemples :

# Affichage simple
idf2table data/OPIO_run.idf Material

# Avec sauvegarde Excel
idf2table data/OPIO_run.idf Material --output materials.xlsx

# Sauvegarde en CSV
idf2table data/OPIO_run.idf Material --csv

💡 Exemples complets

Exemple 1 : Analyse des matériaux

from idf2table import idf_to_table, find_idd
from eppy.modeleditor import IDF
import pandas as pd

# Configuration
idd_path = find_idd()
IDF.setiddname(str(idd_path))
idf = IDF('data/OPIO_run.idf')

# Conversion
materials_df = idf_to_table(idf, "Material")

# Analyse
print(f"Nombre de matériaux : {len(materials_df)}")
print(f"\nColonnes disponibles : {list(materials_df.columns)}")
print("\nMatériaux les plus isolants (faible conductivité) :")
print(materials_df.nsmallest(5, 'Conductivity')[['Name', 'Conductivity', 'Thickness']])

Exemple 2 : Export multiple

from idf2table import idf_to_table, find_idd
from eppy.modeleditor import IDF

# Configuration
idd_path = find_idd()
IDF.setiddname(str(idd_path))
idf = IDF('data/OPIO_run.idf')

# Convertir plusieurs types d'objets
object_types = ["Material", "Construction", "Zone"]

for obj_type in object_types:
    df = idf_to_table(idf, obj_type)
    df.to_excel(f"export_{obj_type}.xlsx", index=False)
    print(f"✓ {obj_type} : {len(df)} objets exportés")

Exemple 3 : Utilisation en ligne de commande

# Convertir Material
idf2table data/OPIO_run.idf Material

# Convertir plusieurs types d'objets
for obj_type in Material Construction Zone; do
    idf2table data/OPIO_run.idf $obj_type --output ${obj_type}.xlsx
done

🗂️ Structure du projet

IDF2TABLE/
├── idf2table/               # Module principal
│   ├── __init__.py          # Exports publics du module
│   ├── core.py              # Fonctions principales (idf_to_table, find_idd)
│   └── cli.py               # Interface en ligne de commande
├── main.py                  # Script d'exemple
├── data/                    # Fichiers IDF
│   ├── OPIO_run.idf
│   └── OPIO_run_hamt.idf
├── pyproject.toml           # Configuration du projet
├── uv.lock                  # Lock file des dépendances
└── README.md                # Documentation

📦 Dépendances

• eppy >= 0.5.66 : Manipulation des fichiers IDF EnergyPlus
• pandas >= 2.3.3 : Manipulation de DataFrames
• openpyxl >= 3.1.5 : Export Excel (inclus)

📦 Installation depuis PyPI

Une fois publié sur PyPI, vous pourrez installer le package avec :

# Installation standard
pip install idf2table

# Ou avec uv
uv pip install idf2table

Publier sur PyPI

Pour publier votre package sur PyPI, suivez les instructions détaillées dans DEPLOYMENT.md.

Résumé rapide :

# 1. Installer les outils
uv add --dev build twine

# 2. Construire le package
uv run python -m build

# 3. Vérifier le package
uv run twine check dist/*

# 4. Publier sur TestPyPI (recommandé d'abord)
uv run twine upload --repository testpypi dist/*

# 5. Publier sur PyPI
uv run twine upload dist/*

Vous aurez besoin d'un token API PyPI : https://pypi.org/manage/account/

⚠️ Notes importantes

• ✅ Le type d'objet peut être spécifié en minuscules, majuscules ou casse mixte (ex: "Material", "MATERIAL", "material")
• ❌ Si aucun objet du type spécifié n'est trouvé, une ValueError est levée avec la liste des types disponibles
• 📋 Si aucun objet n'est trouvé (liste vide), un DataFrame vide est retourné
• 🧹 Les valeurs de type string sont automatiquement nettoyées (espaces supprimés)
• 📝 Le DataFrame inclut toujours une colonne key indiquant le type d'objet

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou une pull request.

📄 Licence

[À compléter selon vos besoins]