# Guide utilisateur des thèmes Terraform

Auteur: Raymond Ostertag,

Ceci est le guide utilisateur pour les thèmes et objets Terraform. Terraform utilise POV-Ray comme langage de description pour les rédiger.

## Table des matières

- Introduction
- Themes utilisateur
  - Nuages
  - Couleurs du ciel
  - Etoiles
  - Texture du terrain
  - Image de lune
  - Image de fond
- Themes complexes
  - Brouillard
  - Eau
  - Type de ciel
  - Lumières
- Objets
  - Objets multiples
  - Objets isolés
- Scripts avancés
- Quelques liens utiles

## Introductions

Terraform utilise POV-Ray comme language de description pour décrire les thèmes ou les objets. Les bases de ce langage sont très simples à comprendre, la difficulté consiste à apprendre toutes les fonctions que POV-Ray délivre et le réglage fin des paramètres. Quelques thèmes utilisent seulement les fonctions de Textures et c'est possible pour un débutant de les rédiger. Ce document est séparé en quatre sections : les thèmes utilisateurs faciles à rédiger et les images, les thèmes plus complexes, les objets et finalement les scripts avancés.

Dans Terraform presque tout est thémable. La première chose à faire est de comprendre l'organisation des fichiers POV-Ray. Les fichiers arrivent avec votre installation dans /usr/share/terraform/ ou /usr/local/share/terraform/. Vous pouvez les lire mais, s'il vous plait, ne les modifiez pas sinon vous auriez rapidement des difficultés. La meilleure solution pour batir des nouveaux thèmes est de le faire dans votre répertoire personnel. Il y a un répertoire .terraform dans votre répertoire personnel, allez-y et mettez-y vos fichiers personnels. Il y a 3 sous-répertoires : image_maps est pour les images pas pour les thèmes, include est le bon répertoire et objects est seulement pour les objets pas pour les thèmes. Bien, allez dans le répertoire include . Ici vous pouvez copier le fichiers des paramètres defaults.inc et changer les paramètres d'ici. Le point le plus important est que maintenant vous pouvez voir les répertoires utilisés pour les thèmes : atmospheres, earth_textures, skies et water

## Themes utilisateurs

Dans le répertoire include/skies/include vous trouvez les thèmes pour les nuages, couleurs de ciel et les étoiles. Ces thèmes sont tous utilisés dans le type de ciel Earth Regular Sky. Quelques autres types de ciel peuvent les utiliser mais ce n'est pas toujours vrai.
Dans le répertoire earth_textures vous trouverez les thèmes pour le terrain. Pour plus d'informations sur la déclaration d'une texture ou d'un pigment, lisez le chapitre idoine dans le POV-Ray manual.

### Nuages

Un thème de nuage est une déclaration de texture. La forme est :

    #declare TF_clouds = texture { TEXTURE_DECLARATION }

C'est important de conserver le nom TF_clouds. L'autre chose importante est de conserver une partie de la texture transparente, la valeur de filter des couleurs ne doit pas être toujours 0. Cette texture est appliquée sur une sphère et derrière cette sphère il y a des objets (lune, soleil) et vous ne les verrez pas s'il n'y a pas de la transparence dans votre texture de nuage. La pire des situations serait d'avoir les lumières derrière une sphère sans transparence : votre image sera noire.
Comment sera déclarée votre texture dépend de ce que vous souhaitez. Il y a quelques exemples de scripts délivrés avec POV-Ray. Vous pouvez utiliser un éditeur de matériaux comme Truevision il y a quelques nuages fournis avec ce programme (enlevez juste le niveau de déclaration : material).
Ce thème est automatiquement scanné et disponible dans la boite de dialogue. Pour un scan réussi conservez le préfixe clouds_ dans le nom du fichier.

### Couleurs de ciel

Un thème de couleurs de ciel est une suite de déclaration de 16 couleurs. La forme est pour chaque couleur :

    #declare *_color   = < Red value, Green value, Blue value > * TF_SKY_COLORATION ;

Faites une copie du fichier skycolor_earth.inc et renommez le skycolor_mars.inc par exemple. Tout ce que vous avez à faire est d'éditer les couleurs et de les changer suivant vos souhaits. Les couleurs sont mélangées pour produire le ciel. Il y a trois sections : les couleurs à midi (noon), la nuit (night) et la transition vers le jour. TF_SKY_COLORATION est un paramètre global qui change la coloration de tout le ciel. Il peut être modifié depuis le fichier defaults.inc.
Ce thème ne peut pas être changé depuis les boites de dialogue, vous devez éditer le fichier defaults.inc et changer l'option TF_SKY_COLORDESCRIPTION.

### Etoiles

Un thème étoiles est une déclaration de pigment. Le pigment est un sous-niveau d'une déclaration de texture. La forme est :

    #declare stars_pigment = pigment { PIGMENT_DECLARATION }

C'est important de conserver le nom stars_pigment. L'autre chose importante est d'ajouter un stars_transmit dans la valeur de transmission (transmit) des couleurs où il n'y a pas d'étoiles et une valeur de 1 là où il y a des étoiles. Cette texture est appliquée sur une sphère, derrière cette sphère il y a le ciel. Si vous oubliez de donner la valeur 1 là où il n'y a pas d'étoiles le ciel en sera affecté. La valeur de stars_transmit est différente suivant le jour ou la nuit, la nuit vous voyez les étoiles, le jour elles ne sont pas visibles, entre le jour et la nuit il y a un facteur pondéré.
Comment sera déclarée votre pigment dépend de ce que vous souhaitez. Il y a quelques exemples de scripts délivrés avec POV-Ray. Vous pouvez utiliser un éditeur de matériaux comme Truevision il y a quelques étoiles fournies avec ce programme (enlevez juste les niveaux de déclaration : material et texture).
Ce thème est automatiquement scanné et disponible dans la boite de dialogue. Pour un scan réussi conservez le préfixe stars_ dans le nom du fichier.

### Texture du terrain

Une texture de terrain est une declaration de la forme :

    #declare TF_clouds = texture { TEXTURE_DECLARATION }

Dans les anciennes versions de Terraform c'étail la seule chose qui était thémable. Si vous en aviez fait ils sont toujours applicable. C'est important de conserver le nom TF_LANDSCAPE_TEXTURE. Cette texture est appliquée sur le terrain (height-field). Vous pouvez déclarer une texture simple ou une texture plus complexe utilisant un gradient Y. Dans ce dernier cas vous pouvez utiliser le paramètre TF_WATER_LEVEL pour créer des des textures dépendantes du niveau de l'eau. Quelques autres paramètres comme TF_LANDSCAPE_TURBULENCE et TF_LANDSCAPE_DISTRIBUTION peuvent aussi être ajouté quelque part dans votre texture. Il y a quelques scripts (simple ou complexe) livrés avec Terraform, vous pouvez partir d'un de ceux-ci ou utiliser l'éditeur de matériaux de Truevision (enlevez juste le niveau de déclaration : material).
Ce thème est automatiquement scanné et disponible dans la boite de dialogue. Pour un scan réussi mettez-le simplement dans le répertoire earth_texture.

### Image de lune

Une carte réelle de la lune est appliquée sur l'objet lune. Cette carte est dans le répertoire image_maps. Elle est au format PNG. La largeur de l'image doit être le double de la hauteur pour éviter les déformations. Vous pouvez trouvez quelques jolies cartes sur le web (Ressources page), presque toutes avec la bonne taille mais au format JPEG., changez juste le format avec Gimp ou ImageMagick. Mettez-la dans le répertoire image_maps. Cette carte ne peut pas être changée depuis les boites de dialogue, vous devez éditer le fichier defaults.inc et changer l'option TF_MOON_IMAGE .
Quelques paramètres de contrôle TF_MOON_Y_ROT et TF_MOON_Z_ROT du fichier defaults.inc peuvent être utilisés pour contrôler quel point de la carte vous verrez avec la caméra. TF_MOON_Y_ROT = 0 et TF_MOON_Z_ROT = 0 montrent la face-que-vous-voyez de la lune. TF_MOON_Y_ROT = 180 et TF_MOON_Z_ROT = 0 montrent la face cachée de la lune. Si vous rendez une carte de la terre à la place de celle de la lune et voulez voir un point spécifique de la terre vous devrez connaitre sa position géographique et changer les rotations comme ceci : TF_MOON_Y_ROT = latitude coordonnée telle que E20=20 W20=-20, TF_MOON_Y_ROT = longitude coordonnée telle que N0=90 S0=-90.

### Image de fond

L'image projetée sur le plan de fond pour le type de ciel Mapped Sky peut être changée. La carte est dans le répertoire image_maps. Elle est au format TGA. La taille doit être au ratio 16/9 pour éviter les déformations, quelques tailles valides sont 1600x900, 800x450, 400x225. Il y a quelques exemples sur le web. Si vous faites une jolie photo d'un soleil couchant et que vous la souhaitiez un image de fond dans Terraform, alors taillez la dans un format 16/9 et sauvegardez-la au format TGA. Mettez le fichier TGA dans le répertoire image_maps. L'image de fond ne peut pas être changée depuis les boites de dialogue. Vous devez éditer le fichier defaults.inc et changer l'option TF_SKY_IMAGE.
Quelques paramètres de contrôle TF_SKY_IMAGE_SCALE et TF_SKY_IMAGE_ELEVATION_OFFSET du fichier defaults.inc peuvent être utilisés pour contrôler le positionnement de l'image de fond.

## Themes complexes

Il y a encore d'autres parties thèmables dans Terraform : les brouillards dans atmospheres, l'eau dans water, les lumières dans skies/include et les type de ciel dans skies. Pour de de plus amples informations sur le langage de script lisez le POV-Ray manual.

### Brouillard

Dans le répertoire atmospheres il y a des fichiers de base commençant par le préfixe earth_ et autres fichiers à inclure dans votre thème de brouillard. Typiquement le thème a cette forme :

    #if (TF_HAVE_FOG)
      FOG_DECLARATION
    #end // TF_HAVE_FOG
    #if (TF_HAVE_GROUND_FOG)
      #include "fog_ground.inc"
    #end // TF_HAVE_GROUND_FOG
    #if (TF_HAVE_RAINBOW)
      #include "rainbow.inc"
    #end // TF_HAVE_RAINBOW

En premier votre description du brouillard ensuite vous incluez les fichiers de brouillard de sol et d'arc-en-ciel. Bien sûr si vous souhaitez changer l'arc-en-ciel vous devrez créer un fichier rainbow2.inc et l'inclure dans un nouveau fichier de base earth_fog2.inc.
Les paramètres dans la section Atmosphere du fichier defaults.inc peuvent être utilisés à votre convenance.
Ce thème est automatiquement scanné et disponible dans la boite de dialogue. Pour un scan réussi conservez le préfixe earth_ dans le nom du fichier.

### Eau

Dans le répertoire water il y a les fichiers de thème pour l'eau commençant avec le préfixe earth_. Typiquement le thème à la forme :

    #if (TF_HAVE_WATER)
      WATER_DECLARATION
    #end // TF_HAVE_WATER

L'eau est un plan infini avec une texture appliquée dessus. Vous pouvez déplacer ce plan à un niveau correspondant à la valeur : TF_WATER_LEVEL * TF_Y_SCALE. Si vous préférez un autre objet pour simuler l'eau, par exemple une boite (box) géante, gardez en tête que les limites du terrain commencent à la coordonnée < 0,0,0 > et finissent à < 1 * TF_X_SCALE, 1 * TF_Y_SCALE, 1 * TF_Z_SCALE >. TF_WATER_LEVEL est une valeur entre 0 et 1, c'est logique. Dès que votre plan ou objet est à la bonne place texturez-le.
Les paramètres dans la section Water du fichier defaults.inc peuvent être utilisés à votre convenance.
Ce thème est automatiquement scanné et disponible dans la boite de dialogue. Pour un scan réussi conservez le préfixe earth_ dans le nom du fichier.

### Type de ciel

Dans le répertoire skies il y a les fichiers pour la description globale du ciel commençant avec le préfixe earth_. Quelques fichiers sont très complexes que le thème Earth Regular quelques autres sont très simples. L'objectif de ces fichiers est de décrire ou ordonner :

- le fond du ciel et les étoiles
- les lumières
- les objets célestes
- les nuages

Les fonctionnalités des types de ciel Terraform sont expliquées dans le fichier documentation du rendu. Vous ne devriez pas partir de rien mais plutôt faire une copie et modifier un fichier existant pour ajouter ou modifier ce que vous voulez. Gardez en tête que les limites du terrain commencent à la coordonnée < 0,0,0 > et finissent à < 1 * TF_X_SCALE, 1 * TF_Y_SCALE, 1 * TF_Z_SCALE >.
Les paramètres dans la section Sky du fichier defaults.inc peuvent être utilisés à votre convenance.
Ce thème est automatiquement scanné et disponible dans la boite de dialogue. Pour un scan réussi mettez-les simplement dans le répertoire skies.

### Lumières

Dans le répertoire skies/include il y a les fichiers pour la description des lumières commençants par le préfixe lights_. Les fichiers ne sont pas toujours des thèmes. Lights_studio est utilisé de le type de ciel Earth Static, c'est un jeu fixe de trois lumières tel que les éclairages Holywoodiens. Lights_toymodel est utilisé dans le type de ciel Earth_Dynamic, c'est un jeu de lumières qui simule l'éclairage du soleil et de la lune avec un éclairage ambient optionnel. Ligths_standard est un thème pour le Type de Ciel principal Earth Regular. Typiquement le thème à la forme :

    #if (TF_HAVE_AMBIENT_LIGHT)
      AMBIENT_LIGHT_DECLARATION
    #end // TF_HAVE_AMBIENT_LIGHT
    #if (TF_HAVE_CAMERA_LIGHT)
      CAMERA_LIGHT_DECLARATION
    #end // TF_HAVE_CAMERA_LIGHT

Gardez en tête que les limites du terrain commencent à la coordonnée < 0,0,0 > et finissent à < 1 * TF_X_SCALE, 1 * TF_Y_SCALE, 1 * TF_Z_SCALE >. Si vous ajoutez un quelconque point d'éclairage n'oubliez pas de mettre les coordonnées à l'échelle avec les paramètres TF_XYZ_SCALE. La posiiton de la caméra peut être obtenu avec le paramètre TF_CAMERA_LOCATION.
Quelques paramètres relatifs aux lumières dans le section Sky du fichier defaults.inc peuvant être utilisés à votre convenance.
Ce thème ne peut pas être changé depuis les boites de dialogue, vous devez éditer le fichier defaults.inc et changer l'option TF_LIGHTS_DESCRIPTION.

## Objets

Les objets sont multiples ou isolés. Les objets multiples sont le standard de Terraform, ils sont disponibles depuis le menu Objets >Mettre en place. Il y a de nombreux paramètres pour choisir comment les répartir sur le terrain. Les objets isolés sont appelés TRACE objets car ils utilisent la fonction Trace de POV-Ray pour être positionnés sur le terrain. Ils ne sont pas accessibles via un menu.

### Objets multiples

Vous pouvez ajouter des objets dans le répertoire objects. Tout type d'objet est acceptable à la condition qu'il soit lisible par POV-Ray. Par exemple vous pouvez décrire un objet avec les fonctions booléennes (CSG) de POV-Ray ou créer un objet avec le modeleur 3D Moonlight et l'exporter comme un mesh. La déclaration de l'objet devra avoir cette forme :

    #declare POV_OBJECT_ NAME = { tout type de déclaration d'objet POV }
       macro OBJECT_NAME ()
       object {  POV_OBJECT_NAME  }
    #end

Le nom du fichier doit être OBJECT_NAME.inc (le même nom que pour la déclaration de la macro).
Ces objets sont automatiquement scannés et disponibles dans la boite de dialogue des objets depuis le menu Opérations. Pour un scan réussi mettez le fichier OBJECT_NAME.inc dans le répertoire object.
Souvent la déclaration de l'objet est séparée en deux fichiers OBJECT_NAME_INC.txt et OBJECT_NAME.inc. Le fichier OBJECT_NAME_INC.txt contient l'objet lui-même et peut être réutilisé comme un objet isolé.

### Objets isolés

Les objets isolés peuvent être partout, sur la terre, l'eau ou dans les airs. Quelques paramètres sont nécessaires pour contrôler le positonnement de l'objet :

- LOCAL_EYE_POINT : position initiale de l'objet en coordonnées absolues comme dans le dialogue de la caméra
- LOCAL_CAMERA_RELATIV : on peut changer le système de coordonnées tel qu'il soit relatif à la position de la caméra
- LOCAL_CONSERVE_ELEVATION : si false l'objet est placé sur la terre ou l'eau
- LOCAL_OBJECT_FLOAT : si false l'objet peut être sur la terre mais aussi sous l'eau
- LOCAL_OBJECT_SCALE : mise à l'échelle de l'objet

Les objets isolés sont listés à la fin du fichier defaults.inc. Vous devez l'éditer. Le fichier de déclaration de l'objet est dans le répertoire include et préfixé par le mot TRACE.

## Scripts avancés

Les scripteurs POV-Ray confirmés peuvent ajouter leurs propres scripts dans Terraform. Terraform construit dynaquement le processus de rendu avec les fichiers thèmes et quelques fichiers statiques de la façon suivante :

- defaults.inc , le fichier des paramètres est lu en premier
- fichiers de themes tels que sky, fog, water, earth texture, objects : la partie dynamique
- generic_land.inc, le fichier de déclaration final.

La meilleure solution et de mettre dans le fichier de déclaration final generic_land.inc une instruction :

    #include "mycustom.inc"

Terraform déclare beaucoup de Library path, utiliser simplement le répertoire include pour stocker vos fichiers personnels, ils seront lus. Bien sût vous pouvez télécharger et intégrer toutes les POV resources du web. La fonction Trace est pratique pour placer des objets isolés à une place particulière dur le terrain.. Gardez juste en mémoire les paramètres de base :

- TF_CAMERA_LOCATION, TF_CAMERA_LOOK_AT : coordonnées de la caméra avec application des échellles
- < 0,0,0 > <1,1,1> : limites du terrain (sans application des échelles)
- TF_X_SCALE, TF_Y_SCALE, TF_Z_SCALE : échelles appliquées au terrain
- TF_SCALE = < TF_X_SCALE, TF_Y_SCALE, TF_Z_SCALE > : facteur d'échelle global, parfois utile
- TF_WATER_LEVEL : niveau de l'eau, sans échelle

## Quelques liens utiles

POV-Ray documentation, Table des matières
POV-Ray documentation, Chapitre Textures simples
POV-Ray documentation, Textures avancées
Ressources pour des images de fond
Ressourcespour des cartes de lunes
Ressources pour des scripts POV-Ray