Exporteurs et importateurs

TopSolid expose un systeme de plugins pour les echanges de fichiers. Chaque format (STEP, DXF, PDF, glTF...) est un exporteur ou un importateur enregistre dans l'application avec un index dynamique. Ce document decrit comment les decouvrir, les parametrer et les utiliser depuis l'API Automation — directement en C# ou via les recettes MCP.

Decouvrir les formats installes

L'index d'un exporteur n'est pas stable : il depend de la liste de plugins installes sur le poste de travail (et des licences actives). Ne jamais hardcoder un index — toujours le chercher a runtime par extension ou par nom.

int total = TopSolidHost.Application.ExporterCount;
for (int i = 0; i < total; i++)
{
    if (!TopSolidHost.Application.IsExporterValid(i)) continue;   // licence manquante ?
    string typeName;
    string[] extensions;
    TopSolidHost.Application.GetExporterFileType(i, out typeName, out extensions);
    Console.WriteLine($"{i}: {typeName} -> [{string.Join(", ", extensions)}]");
}

Le symetrique existe pour les importateurs : ImporterCount, IsImporterValid, GetImporterFileType.

Recettes pretes a l'emploi (v1.8.16)

import_file et export_file font tout le travail decrit ici : choix de l'importeur ou de l'exporteur par l'extension, controle de licence, mode silencieux, et refus d'exporter un document sans forme. Voir Recettes.

Workflow d'export

1. Trouver l'index par extension
     ↓
2. Verifier IsExporterValid(i)  (licence dispo)
     ↓
3. Verifier CanExport(i, docId)  (type de document compatible)
     ↓
3b. Format 3D : verifier IShapes.GetShapes(docId).Count > 0
     ↓
4a. Export(i, docId, fullPath)                   ← simple
    OU
4b. ExportWithOptions(i, options, docId, path)   ← avec options

Jamais d'export 3D d'un document sans forme

Exporter en STEP, IGES, STL, Parasolid... un document dont la representation detaillee est vide (TopSolidHost.Shapes.GetShapes(docId).Count == 0) ouvre la boite modale « aucune entite a exporter ». Le mode silencieux (IS_TRANSLATOR_SILENT=True) ne l'empeche pas : TopSolid reste bloque, le script expire au bout de 60 s et TopSolid peut finir par tomber. Cas typique : un assemblage importe (SolidWorks...) garde sa geometrie dans ses pieces. Exporter ses pieces une par une. topsolid_detect_dialog lit la boite si elle est deja ouverte.

Recette minimale (lookup + export)

int idx = FindExporterIndex(".stp");
if (idx < 0) throw new Exception("Aucun exporteur STEP installe.");
if (!TopSolidHost.Application.IsExporterValid(idx)) throw new Exception("Licence STEP manquante.");
if (!TopSolidHost.Documents.CanExport(idx, docId)) throw new Exception("Ce document ne peut pas etre exporte en STEP.");
TopSolidHost.Documents.Export(idx, docId, @"C:\temp\part.stp");

int FindExporterIndex(string ext)
{
    int count = TopSolidHost.Application.ExporterCount;
    for (int i = 0; i < count; i++)
    {
        string name; string[] exts;
        TopSolidHost.Application.GetExporterFileType(i, out name, out exts);
        foreach (var e in exts)
            if (e.Equals(ext, StringComparison.OrdinalIgnoreCase)) return i;
    }
    return -1;
}

Export avec options

Certains formats (FBX, glTF, STEP AP242, PDF 3D) acceptent des options cle-valeur :

List<KeyValue> options = TopSolidHost.Application.GetExporterOptions(idx);
// options contient les defauts. Lister + inspecter pour decouvrir ce qui est dispo.
foreach (var kv in options) Console.WriteLine($"{kv.Key} = {kv.Value}");

// Modifier une option (remplacer l'entree dans la liste)
for (int i = 0; i < options.Count; i++)
{
    if (options[i].Key == "EXPORTS_CAMERAS")
        options[i] = new KeyValue("EXPORTS_CAMERAS", "True");
}

TopSolidHost.Documents.ExportWithOptions(idx, options, docId, @"C:\temp\part.gltf");

Options ne sont pas documentees officiellement

Les cles d'options varient par exporteur et par version de TopSolid. Toujours lister via GetExporterOptions() d'abord pour voir ce qui est expose, puis modifier. Ne pas supposer qu'une cle d'un format existe sur un autre.

Formats couramment installes

Le tableau ci-dessous est donne a titre indicatif — verifiez toujours l'installation reelle via ExporterCount. Les extensions peuvent etre en plusieurs variantes (.stp / .step, .gltf / .glb...).

Format	Extension	Usage metier	Options courantes	Licence requise
STEP AP214/AP242	.stp .step	Echange 3D universel CAO-a-CAO. Le plus interoperable.	WRITE_PMI, PROTOCOL	Inclus
IGES	.igs .iges	Echange 3D legacy (precede STEP)	—	Inclus
Parasolid	.x_t .x_b	Echange natif avec SolidWorks, NX, Fusion	—	Inclus
STL	.stl	Impression 3D, maillage triangles	RESOLUTION, BINARY	Inclus
DXF / DWG	.dxf .dwg	Mises a plat toleric (laser), mises en plan 2D	VERSION, LAYERS	Inclus
PDF	.pdf	Diffusion mise en plan + 3D PDF	COMPRESSION, LAYERS, EMBEDS_MODEL (3D PDF)	Inclus
FBX	.fbx	Visualisation 3D, VR, moteurs jeu	EXPORTS_CAMERAS, EXPORTS_LIGHTS, REPRESENTATION_ID	Inclus
glTF / GLB	.gltf .glb	Web 3D, AR, digital twin	EXPORTS_CAMERAS, EXPORTS_LIGHTS, EMBEDS_BUFFER, MAX_TEXTURE_SIZE	Inclus
IFC	.ifc	Batiment (BIM)	MVD, UNITS	TopSolid'Steel ou TopSolid'Wood
3D XML	.3dxml	Diffusion Dassault Systemes	—	Inclus
JT	.jt	Echange Siemens (automotive, aero)	LEVEL_OF_DETAIL	Inclus

Importateurs

La mecanique est identique cote import :

int idx = FindImporterIndex(".stp");
PdmObjectId folder = /* un dossier PDM ou stocker les resultats */;
List<string> log;
List<DocumentId> badDocs;
List<DocumentId> importedDocs = TopSolidHost.Documents.Import(idx, @"C:\temp\data.stp", folder, out log, out badDocs);

foreach (var msg in log) Console.WriteLine("[Import] " + msg);
if (badDocs.Count > 0) Console.WriteLine("WARN: " + badDocs.Count + " documents importes avec erreurs.");

Pour ImportWithOptions, la logique est identique : GetImporterOptions(idx) puis passer la liste modifiee. Mettre IS_TRANSLATOR_SILENT=True pour eviter les boites de dialogue de l'importeur. La recette import_file fait tout cela pour un fichier.

Ce que cree l'importeur SolidWorks (Spatial)

Constate sur TopSolid 7.20, importeur « SolidWorks (Spatial) » (.sldprt, .sldasm, .slddrw) :

Fichier source	Documents crees
SLDPRT d'un seul corps	une .TopPrt et un .TopMat (avec TRANSLATES_MATERIAL=True)
SLDPRT de plusieurs corps	une .TopAsm et un sous-dossier de .TopPrt, une par corps
SLDASM	une .TopAsm et des pieces nommees « Copie de <ref>^<assemblage> »

Consequences :

• la .TopAsm creee n'a aucune forme dans sa representation detaillee : exporter ses pieces, pas elle (voir l'encadre plus haut) ;
• ne jamais prendre le premier document cree a l'aveugle : ce peut etre l'assemblage vide ou un materiau. Filtrer sur Shapes.GetShapes(doc).Count > 0 ;
• chaque import cree son propre .TopMat : pour un import en lot, regrouper les materiaux de meme nom.

Importer dans un modele precis (Wooden Part, etc.)

Documents.Import ne prend pas de modele en parametre : chaque fichier importe devient un nouveau document construit avec le modele par defaut du type de document dans le projet cible (cf. Pdm.CreateDocument(inOwnerId, inExtension, inUseDefaultTemplate)). Impossible donc de garantir via Import seul qu'un STEP donne sera un "Wooden Part".

Par ailleurs, l'API TopSolid refuse la creation de document dans une transaction de modification — remarque officielle des pages IPdm.CreateDocument et IPdm.CreateDocumentWithTemplate :

This method must not be called between StartModification(String, Boolean) and EndModification(Boolean, Boolean).

Le serveur MCP enveloppe automatiquement dans une transaction StartModification/EndModification tout code detecte comme ecriture : topsolid_execute_script (auto-detection), topsolid_modify_script, et toutes les recettes declarees RW (Pattern D). Depuis la v1.8.16, un script dont les seules ecritures sont des appels PDM ou document refuses en transaction (CreateDocumentWithTemplate, CreateFolder, Documents.Open...) s'execute sans transaction. Un script qui les melange a des modifications du modele est refuse avant execution, avec la liste des appels en cause (voir Outils MCP).

Deux solutions :

1. Recette create_document_with_template (mode [WRITE-PDM-NO-TRX] — hors transaction par design) : cree dans le projet courant un document a partir d'un modele nomme, cherche dans les projets de modeles utilisateur et societe (Pdm.GetTemplates + SearchDocumentByName).

   topsolid_run_recipe avec recipe=create_document_with_template, value=Wooden Part

   Limites a connaitre : Documents.Import ne peut PAS viser ce document (il importe dans un dossier PDM et cree ses propres documents) ; pour y reporter la geometrie d'un STEP, ouvrir le document et importer depuis l'interface TopSolid, ou copier les elements depuis le document importe. La creation est la seule operation faite par la recette.

2. Modele .TopPrt par defaut du projet : definir "Wooden Part" comme modele par defaut du type .TopPrt dans les proprietes du projet (interface TopSolid). Documents.Import produit alors directement des documents bases sur ce modele — c'est la voie naturelle quand tous les documents .TopPrt du projet doivent suivre ce modele, et elle rend la question de la transaction sans objet pour l'import.

Recettes MCP disponibles

Les recettes actuelles couvrent les 5 formats les plus demandes :

Recette	Format	Mode	value
list_exporters	—	R	(aucun) — liste tous les formats + leurs index runtime
export_step	STEP	R	chemin de sortie (C:\temp\piece.stp)
export_dxf	DXF	R	chemin de sortie
export_pdf	PDF	R	chemin de sortie
export_stl	STL	R	chemin de sortie
export_iges	IGES	R	chemin de sortie
export_bom_csv	CSV (nomenclature)	R	chemin de sortie
create_document_with_template	— (modele de document)	RN	nom du modele (ex: Wooden Part)

Ces recettes encapsulent la boucle FindExporterIndex() et verifient CanExport() avant d'appeler Export(). Pour un format absent de la liste (FBX, glTF, IFC...), utiliser topsolid_execute_script avec le pattern ci-dessus, ou demander l'ajout d'une recette dediee.

Patterns batch

Exporter tout un projet en STEP

PdmObjectId proj = TopSolidHost.Pdm.GetCurrentProject();
var allDocs = TopSolidHost.Pdm.GetConstituents(proj, true);  // true = recursif
int idx = FindExporterIndex(".stp");

foreach (var pdmId in allDocs)
{
    string type = ""; TopSolidHost.Pdm.GetType(pdmId, out type);
    if (type != ".TopPrt" && type != ".TopAsm") continue;  // pieces + assemblages seulement
    DocumentId docId = TopSolidHost.Documents.GetDocument(pdmId);
    if (!TopSolidHost.Documents.CanExport(idx, docId)) continue;
    string name = TopSolidHost.Pdm.GetName(pdmId);
    string path = Path.Combine(@"C:\exports", name + ".stp");
    try { TopSolidHost.Documents.Export(idx, docId, path); }
    catch (Exception ex) { Console.Error.WriteLine("FAIL " + name + ": " + ex.Message); }
}

Exporter une mise en plan multi-pages en PDF

La mise en plan est naturellement multi-page : l'exporteur PDF produit un seul PDF avec toutes les pages dans l'ordre.

// Le document actif doit etre une mise en plan (IsDrafting == true)
int idx = FindExporterIndex(".pdf");
TopSolidHost.Documents.Export(idx, docId, @"C:\exports\plan.pdf");
// 3 pages -> 1 PDF de 3 pages

Pieges courants

Piege	Symptome	Solution
Index hardcode	Export silencieusement au mauvais format apres une maj TopSolid	Toujours faire FindExporterIndex(ext) a runtime
IsExporterValid = false	Export() leve une exception peu claire	Verifier la licence du format cible ; certains formats (IFC, 3D PDF avance) necessitent des modules TopSolid specifiques
Chemin sans le dossier cree	Exception DirectoryNotFoundException	Directory.CreateDirectory(Path.GetDirectoryName(path)) avant l'export
Unites melangees	STL / glTF sortent en m au lieu de mm attendus	Verifier le parametre d'unite du document source (Document.Units) avant export. TopSolid utilise le SI (metres) en interne
Export d'assemblage sans les parts	Fichier vide ou incomplet	Verifier CanExport + que les inclusions sont a jour (Rebuild avant export)
Caracteres non-ASCII dans le chemin	Exception ou fichier corrompu selon l'exporteur	Prefixer avec \\?\ sur Windows, ou migrer vers un chemin ASCII sur (C:\temp)
Export depuis un doc dirty	Le fichier contient la version SAUVEGARDEE, pas la version en cours	Pdm.Save(pdmId, true) avant l'export
Export d'un document sans forme	Boite modale « aucune entite a exporter », TopSolid gele puis peut tomber	Shapes.GetShapes(docId).Count > 0 avant tout export 3D ; recette export_file
PdmObjectId.ToString() comme cle	Tous les objets semblent identiques (meme texte = nom du type)	Garder le PdmObjectId comme cle, comparer avec Equals
Documents.IsOpen	Erreur de compilation : la methode n'existe pas	Documents.GetOpenDocuments().Contains(docId)
Creation de document dans une transaction	CreateDocument / CreateDocumentWithTemplate rejetes par TopSolid, aucun document cree	Recette create_document_with_template (mode RN, hors transaction), ou definir le modele par defaut du projet

Utilisation standalone (hors MCP)

Pour un developpeur qui ecrit une app .NET Framework 4.8 TopSolid Automation directement (pas via MCP), le code est identique — il suffit d'instancier TopSolidHost via TopSolidHost.Connect(). Voir knowledge-base.md pour le workflow complet de generation d'apps C# standalone a partir des recettes MCP.

Les recettes de ce tableau sont self-contained — chacune peut etre extraite en un Run() method C# et compilee dans un exe separe. Utiliser topsolid_get_recipe("export_step") pour en obtenir le code source.

Exports speciaux non-Documents

Quelques methodes d'export ne passent pas par IDocuments :

Methode	Usage
IPdm.ExportPackage(pdmId, path, options)	Package TopSolid .TopPkg (archive PDM complete)
IPdm.ExportViewerPackage(pdmId, path, options)	Package viewer lisible par TopSolid Viewer gratuit
IPdm.ExportToBabylon(pdmId, path)	Format Babylon.js (web 3D)
IDocuments.zExportToTopglTF(...)	Export glTF direct avec 12 parametres cameras/lights/faces/sets/materials/textureSize/edgesColor (bypasse le systeme de plugins)

La forme avec z en prefixe indique une API interne "non stable" — son nom peut changer entre versions. Preferez l'exporteur glTF standard via Export(idx) quand possible.