Personnalisation du processus d'importation de Datasmith

L'objectif du processus d'importation de Datasmith est d'importer facilement un ensemble d'objets 3D que vous avez configurés dans un outil de création de contenu dans l'Unreal Editor. Pour ce faire, il convertit automatiquement les objets tels que les maillages, les lumières, les caméras et les matériaux de surface en leurs équivalents dans l'Unreal Engine tout en faisant de son mieux pour respecter l'intention de votre conception. Il remplit ensuite automatiquement un niveau avec des instances de ces ressources pour vous. Pour plus de détails, voir Présentation de Datasmith.

Cependant, il peut arriver que vous souhaitiez intervenir dans le processus d'importation pour modifier la manière dont il convertit votre scène originale en ressources d'Unreal Engine, ou pour ajuster ce qu'il fait de ces ressources. Par exemple, s'il y a des parties de votre scène d'origine dont vous savez que vous n'aurez pas besoin dans votre projet Unreal Engine, vous pouvez filtrer ces objets avant de créer vos ressources. Cela réduit le nombre d'éléments de contenu différents que vous devez gérer dans l'Unreal Editor et peut accélérer l'importation de scènes de grande taille.

Cette page vous explique comment utiliser les scripts Blueprint ou Python pour prendre le contrôle du processus d'importation de Datasmith.

Comprendre le processus d'importation

Lorsque vous importez une scène à l'aide de l'un des importateurs Datasmith dans la barre d'outils de l'Unreal Editor, comme décrit dans Importer du contenu Datasmith dans l'Unreal Engine, l'importateur exécute en interne un processus en deux étapes pour extraire vos données d'un fichier source .udatasmith, CAO ou d'un autre fichier sur le disque et les transformer en ressources et en acteurs dans l'Unreal Editor :

1. L'importateur lit le contenu du fichier dans une structure de données en mémoire appelée scène Datasmith. Il contient une représentation des objets 3D de la scène, de leurs relations et de toutes les propriétés de ces objets que Datasmith a pu extraire de votre scène d'origine.
2. Lorsque la scène Datasmith est prête en mémoire, une deuxième étape du processus d'importation finalise les éléments de la scène dans les ressources Unreal Engine dans le navigateur de contenu. Lorsque la ressource de scène Datasmith est prête, le processus d'importation la fait apparaître dans le niveau actuel. Cela fait apparaître en retour tous ses enfants : acteurs, acteurs à maillage statique, lumières, caméras, etc.

Options de personnalisation du processus d'importation

Si vous utilisez un script Blueprint ou Python pour lancer le processus d'importation de Datasmith, vous pouvez déconstruire le processus ci-dessus et effectuer chacune des deux étapes séparément. Cela vous permet d'insérer votre propre traitement après avoir construit la scène Datasmith en mémoire, mais avant de finaliser cette scène dans les ressources et les acteurs.

Le processus global est le même pour Blueprint et Python :

1. Construisez une nouvelle représentation de scène Datasmith en mémoire à partir de l'emplacement d'un fichier .udatasmith, CAO ou d'un autre type de fichier pris en charge sur le disque.

2. Effectuez toutes les modifications de scène supplémentaires que vous souhaitez afin d'influencer la manière dont votre scène est transformée en ressources dans Unreal.

   Pour faciliter l'identification des objets à modifier, vous pouvez notamment tirer parti des métadonnées relatives aux objets de votre scène. Pour plus de détails sur la façon d'accéder aux métadonnées dans la scène Datasmith, voir Utiliser les métadonnées Datasmith.

3. Configurez les options du processus d'importation. Ces options sont essentiellement équivalentes à celles que vous configurez dans l'interface utilisateur d'Unreal Editor lorsque vous utilisez le bouton Import Datasmith pour démarrer l'importation. Par exemple, vous définissez le chemin où l'importateur doit placer vos ressources importées dans votre projet, les types d'objets qu'il doit créer à partir de la scène Datasmith, les paramètres de tessellation pour les formats de CAO paramétriques, etc.
4. Terminez le processus d'importation pour finaliser votre scène Datasmith dans Unreal Assets.
5. Lorsque vous n'avez plus besoin de la scène Datasmith que vous avez construite ci-dessus, vous devez la détruire afin d'effacer les ressources mémoire qu'elle utilise.
6. Maintenant que le processus d'importation est terminé, vos nouvelles ressources sont disponibles dans le navigateur de contenu et vos nouveaux acteurs sont disponibles dans le niveau actuel (si vous avez demandé qu'ils soient ajoutés à vos options d'importation). Si vous souhaitez effectuer un post-traitement supplémentaire sur les ressources Unreal générées, comme la création automatique de données de collision ou de niveaux de détail (LOD), c'est le moment idéal pour le faire. Voir également Rédaction de scripts et automatisation de l'éditeur.

Avant de commencer

• Assurez-vous que le plug-in Datasmith Importer est activé pour votre projet.
• Pour obtenir des informations générales sur l'utilisation des scripts Blueprint et Python dans l'éditeur, consultez les pages de la documentation Rédaction de scripts et automatisation de l'éditeur.

Exemples

Les exemples suivants montrent comment utiliser Blueprint et Python pour personnaliser le processus d'importation d'un fichier .udatasmith et d'un fichier CAO dans l'Unreal Editor.

    import unreal

    ds_file_on_disk = "C:\\scenes\\building.udatasmith"
    ds_scene_in_memory = unreal.DatasmithSceneElement.construct_datasmith_scene_from_file(ds_file_on_disk)

    if ds_scene_in_memory is None:
        print "Le chargement de la scène a échoué."
        quit()

    # Modifier les données de la scène pour filtrer ou combiner des éléments…

    # Supprimer tout maillage dont le nom contient un certain mot-clé.
    remove_keyword = "exterior"      # nous supprimerons tous les acteurs contenant cette chaîne dans leur nom.
    meshes_to_skip = set([])         # nous utiliserons cet ensemble pour stocker temporairement les maillages dont nous n'avons pas besoin.

    # Supprimer de la scène tous les acteurs de maillage dont les noms correspondent à la chaîne définie ci-dessus.
    pour mesh_actor dans ds_scene_in_memory.get_all_mesh_actors():
        actor_label = mesh_actor.get_label()
        if remove_keyword in actor_label:
            print("suppression de l'acteur nommé : " + actor_label)
            # ajouter la ressource de maillage de cet acteur à la liste des maillages à ignorer
            mesh = mesh_actor.get_mesh_element()
            meshes_to_skip.add(mesh)
            ds_scene_in_memory.remove_mesh_actor(mesh_actor)

    # Supprimer tous les maillages que nous n'avons pas besoin d'importer.
    for mesh in meshes_to_skip:
        mesh_name = mesh.get_element_name()
        print("suppression du maillage nommé " + mesh_name)
        ds_scene_in_memory.remove_mesh(mesh)

    # Définir les options d'importation.
    import_options = ds_scene_in_memory.get_options(unreal.DatasmithImportOptions)
    import_options.base_options.scene_handling = unreal.DatasmithImportScene.NEW_LEVEL

    # Finaliser le processus en créant des ressources et des acteurs.

    # Votre dossier de destination doit commencer par /Game/
    result = ds_scene_in_memory.import_scene("/Game/MyStudioScene")

    if not result.import_succeed:
        print "L'importation a échoué."
        quit()

    # Nettoyer la scène Datasmith.
    ds_scene_in_memory.destroy_scene()
    print "Le processus d'importation personnalisé est terminé !"

Copy full snippet

    import unreal

    # Construire la scène CAO Datasmith à partir d'un fichier sur le disque.
    # Votre dossier de destination doit commencer par /Game/
    ds_file_on_disk = "C:\\designs\\Clutch assembly.SLDASM"
    ds_scene_in_memory = unreal.DatasmithSceneElement.construct_datasmith_scene_from_file(ds_file_on_disk)

    if ds_scene_in_memory is None:
        print "Le chargement de la scène a échoué."
        quit()

    # Modifier les données de la scène pour filtrer ou combiner des éléments.
    remove_keyword = "_BODY"         # nous supprimerons tous les acteurs contenant cette chaîne dans leur nom.
    meshes_to_skip = set([])         # nous utiliserons cet ensemble pour stocker temporairement les maillages dont nous n'avons pas besoin.

    # Supprimer de la scène tous les acteurs de maillage dont les noms correspondent à la chaîne définie ci-dessus.
    pour mesh_actor dans ds_scene_in_memory.get_all_mesh_actors():
        actor_label = mesh_actor.get_label()
        if remove_keyword in actor_label:
            print("suppression de l'acteur nommé : " + actor_label)
            # ajouter la ressource de maillage de cet acteur à la liste des maillages à ignorer
            mesh = mesh_actor.get_mesh_element()
            meshes_to_skip.add(mesh)
            ds_scene_in_memory.remove_mesh_actor(mesh_actor)

    # Supprimer tous les maillages que nous n'avons pas besoin d'importer.
    for mesh in meshes_to_skip:
        mesh_name = mesh.get_element_name()
        print("suppression du maillage nommé " + mesh_name)
        ds_scene_in_memory.remove_mesh(mesh)

    # Définir les options d'importation.

    # Principales options d'importation :
    import_options = ds_scene_in_memory.get_options(unreal.DatasmithImportOptions)
    import_options.base_options.scene_handling = unreal.DatasmithImportScene.NEW_LEVEL

    # Options de tessellation de surface réservées à la CAO :
    tessellation_options = ds_scene_in_memory.get_options(unreal.DatasmithCommonTessellationOptions)
    tessellation_options.options.chord_tolerance = 0.1
    tessellation_options.options.max_edge_length = 0
    tessellation_options.options.normal_tolerance = 30
    tessellation_options.options.stitching_technique = unreal.DatasmithCADStitchingTechnique.STITCHING_SEW

    # Options supplémentaires réservées à la CAO :
    cad_import_options = ds_scene_in_memory.get_options(unreal.DatasmithCADImportOptions)
    cad_import_options.uv_generation = unreal.CADUVGeneration.KEEP
    cad_import_options.num_threads = 8

    # Finaliser le processus en créant des ressources et des acteurs.
    ds_scene_in_memory.import_scene("/Game/MyCADScene")

    # Nettoyer la scène Datasmith.
    ds_scene_in_memory.destroy_scene()
    print "Le processus d'importation personnalisé est terminé !"

Copy full snippet

Accéder aux options d'importation

Lorsque vous travaillez avec différents types de fichiers sources Datasmith, la seule différence dans l'API est que différents types de fichiers vous offrent différentes options de contrôle de l'opération d'importation.

• Pour les fichiers .udatasmith, le premier exemple ci-dessus montre comment vous pouvez accéder à un objet DatasmithImportOptions qui donne accès aux noms de ressource et de chemin de destination, aux types de données que l'on souhaite importer, aux paramètres de résolution de la texture de lumière, etc. Cela fonctionne pour tous les types de fichiers que vous pouvez importer avec Datasmith.

• Pour les fichiers CAO, le deuxième exemple montre comment vous pouvez également accéder à un objet DatasmithCommonTessellationOptions qui contrôle les paramètres utilisés dans le processus de tessellation, et à un objet DatasmithCADImportOptions qui offre l'accès à d'autres paramètres de débogage internes que vous pourriez trouver utiles.

• D'autres types de fichiers pris en charge par Datasmith encapsulent leurs paramètres d'importation dans d'autres classes, telles que DatasmithC4DImportOptions pour Cinema 4 D.

Outre l'accès à ces options d'importation, le reste des scripts permettant de travailler avec la scène Datasmith et les éléments à l'intérieur de la scène sont exactement les mêmes.

Pour plus de détails sur ces classes d'options d'importation et les paramètres qu'elles offrent, consultez leurs entrées dans la Référence de l'API Python ou la Référence de l'API de blueprint.

Comme alternative à l'utilisation de DatasmithSceneElement.get_options() dans Python ou Datasmith > Scene > Get Options dans Blueprint, vous pouvez utiliser DatasmithSceneElement.get_all_options() ou Datasmith > Scene > Get All Options pour récupérer toutes les classes d'options pour la scène Datasmith que vous avez construite dans un seul mappage. La valeur clé de chaque entrée du mappage est une classe d'options appartenant à l'élément de scène Datasmith que vous avez construit à partir de votre fichier, et la valeur de l'entrée est l'instance de cette classe appartenant à l'élément de scène Datasmith. Si vous ne savez pas quel type de fichier votre script va gérer, et donc quels types de classes d'options DatasmithSceneElement doit contenir, vous pouvez utiliser cette approche pour les récupérer toutes et les parcourir.

À propos de la scène Datasmith

Afin d'explorer ce que vous pouvez faire avec la scène Datasmith pendant la phase de pré-importation, il est utile d'en savoir un peu sur la manière dont la scène est construite.

Contenu de la scène

Une scène Datasmith est principalement un conteneur pour différents types d'éléments. Chacun de ces éléments représente soit une ressource qui sera créée dans votre navigateur de contenu après l'importation, soit un acteur qui sera généré dans votre niveau avec sa propre transformation particulière dans l'espace 3D.

Les principaux types d'éléments de ressources sont les suivants :

• Maillages : Chaque élément de maillage représente un bloc de géométrie 3D. Une fois l'importation terminée, chaque élément de maillage se transforme en objet de maillage statique distinct dans le dossier Geometry. Chaque élément de maillage possède un certain nombre de créneaux de matériaux, chacun étant associé par nom à des éléments de matériau.
• Matériaux : Chaque élément de matériau représente un type de surface distinct nécessaire à vos géométries. Une fois l'importation terminée, chaque élément de matériau se transforme en objet de matériau distinct dans le dossier Materials.
• Textures : Chaque élément de texture représente une seule image 2D utilisée par au moins un de vos matériaux. Une fois l'importation terminée, chaque élément de texture se retrouve sous la forme d'un objet Texture distinct dans le dossier Textures.

Les principaux types d'éléments acteurs sont les suivants :

• Acteurs de maillage : Chaque élément d'acteur de maillage représente une instance d'une géométrie de maillage dans votre niveau. Une fois l'importation terminée, chaque élément d'acteur de maillage se transforme en acteur à maillage statique dans votre Organiseur du monde.
• Acteurs de lumière : Chaque élément d'acteur de lumière représente un émetteur de lumière dans votre scène. Une fois l'importation terminée, chaque élément d'acteur de lumière se retrouve dans votre niveau sous la forme d'une instance de type de lumière Unreal de base, tel qu'un point lumineux ou un projecteur, ou sous la forme d'un acteur Datasmith personnalisé qui simule un éclairage de zone. Vous pouvez obtenir et définir un certain nombre de propriétés sur ces lumières, telles que leur intensité, leur couleur, leurs fichiers de texture de profil IES, etc.
• Acteurs de caméra : Chaque caméra représente un point de vue configuré dans votre scène source. Une fois l'importation terminée, chaque élément d'acteur de caméra est ajouté à votre niveau comme un acteur CineCameraActor. Vous pouvez obtenir et définir certaines propriétés de base sur ces acteurs de caméra, telles que leurs proportions.

Les données contenues dans la scène Datasmith en mémoire sont très similaires à celles que vous verriez dans un fichier .udatasmith si vous l'ouvriez. Si vous utilisez 3ds Max ou Sketchup, vous pouvez ouvrir n'importe quel fichier .udatasmith exporté pour vous faire une idée de la manière dont l'objet de scène Datasmith est construit :

Utiliser la scène Datasmith

Vous interagirez principalement avec la scène Datasmith afin de récupérer des listes des éléments décrits ci-dessus. Pour ce faire sous Python, vous utiliserez les fonctions définies dans la classe DatasmithSceneElementBase dont votre DatasmithSceneElement dérive. Dans le blueprint, vous utiliserez les nœuds Datasmith > Scene comme indiqué dans les exemples ci-dessus.

Une fois que vous disposez d'une liste d'éléments, vous pouvez la parcourir pour en extraire un élément particulier. Utilisez ensuite l'API Python pour cet élément (comme DatasmithMeshActorElement), ou les nœuds Datasmith > Element dans le blueprint, pour obtenir et définir des informations sur cet élément particulier. Si votre élément est de type Acteur, vous pouvez également obtenir ses éléments acteurs enfants, ce qui vous permet de parcourir vers le bas la hiérarchie de la scène.

Si vous souhaitez supprimer des éléments existants de la scène (comme indiqué dans les exemples ci-dessus), ou ajouter de nouveaux éléments, vous pouvez également le faire via les fonctions exposées aux mêmes endroits. Par exemple, vous pouvez réorganiser la hiérarchie des acteurs en les supprimant et en les rajoutant sous des parents différents, en utilisant les fonctions exposées par votre classe DatasmithSceneElement en Python, ou les nœuds de la catégorie Datasmith > Scene dans le blueprint.