Problema de nomenclatura topológica
Introdução
O problema de nomenclatura topológica no FreeCAD refere-se ao problema da mudança de nome interno de uma forma após a realização de uma operação de modelagem (extrusão, corte, união, chanfro, filete, etc.). Isso resultará na quebra ou no cálculo incorreto de outros recursos paramétricos que dependem dessa forma. Esse problema afeta todos os objetos no FreeCAD, mas é especialmente notável na construção de sólidos com a bancada de trabalho PartDesign e ao dimensionar esses sólidos com a
bancada de trabalho TechDraw. * Em
PartDesign, se um atributo for aplicado em uma face (ou borda ou vértice), o atributo poderá quebrar se o sólido subjacente mudar de tamanho ou orientação, pois a face original (ou borda ou vértice) poderá ser renomeada internamente. * No
TechDraw, se uma dimensão estiver medindo o comprimento de uma borda desenhada, a dimensão poderá ser quebrada se o modelo 3D for alterado, pois os vértices poderão ser renomeados, alterando assim a borda mensurada.
A questão da nomeação topológica é um problema complexo na modelagem CAD que decorre da maneira como as rotinas internas do FreeCAD lidam com as atualizações das formas geométricas criadas com o kernel OCCT. Esse problema não é exclusivo do FreeCAD. Em geral, ele está presente em softwares de CAD, mas a maioria dos outros softwares de CAD tem heurísticas para reduzir o impacto do problema sobre os usuários.
A partir do FreeCAD 0.19, há esforços contínuos de desenvolvimento para aprimorar a manipulação central de formas, a fim de reduzir o impacto desses problemas. O algoritmo de nomeação descrito no tópico do fórum Topological Naming, My Take foi projetado para reduzir o esforço manual, às vezes corrigindo automaticamente os problemas e outras vezes apresentando uma solução provável ou, pelo menos, mostrando claramente o que causou o problema. A primeira versão estável do FreeCAD a apresentar esse novo algoritmo de nomeação será a 1.0. Com o tempo, esse algoritmo será aplicado a mais partes do FreeCAD, e mais reparos automáticos e assistidos serão adicionados em versões posteriores.
O problema de nomeação topológica geralmente afeta e confunde os novos usuários do FreeCAD. No PartDesign, o usuário é aconselhado a seguir as práticas recomendadas discutidas na página edição de recursos. O uso de objetos de dados de suporte como plano de referência e criar um sistema de coordenadas local é altamente recomendado para produzir modelos que não estejam facilmente sujeitos a esses erros topológicos. No TechDraw, o usuário é aconselhado a adicionar dimensões somente quando o modelo 3D estiver completo e não for modificado posteriormente.
Exemplo
1. Na bancada de trabalho PartDesign, crie um
Corpo e, em seguida, use
criar esboço e selecione o plano XY para desenhar; em seguida, execute um
preencher para criar o primeiro sólido.
2. Selecione a face superior do sólido anterior e, em seguida, use criar esboço para desenhar outro esboço; em seguida, execute um segundo preencher.
![]() |
![]() |
3. Selecione a face superior da extrusão anterior e, mais uma vez, crie um esboço e um bloco com preencher.
4. Agora, clique duas vezes no segundo esboço e modifique-o de modo que seu comprimento esteja ao longo da direção X; isso recriará o segundo preencher. O terceiro esboço e o bloco permanecerão no mesmo lugar.
![]() |
![]() |
5. Agora, clique duas vezes no segundo (Sketch001) esboço novamente e ajuste seus pontos de modo que uma parte dele fique fora dos limites definidos pelo primeiro bloco. Ao fazer isso, o segundo bloco será recomputado corretamente; no entanto, ao examinar a vista em árvore, será indicado um erro no terceiro bloco.
![]() |
![]() |
6. Ao tornar visíveis o terceiro esboço e o bloco, fica claro que o cálculo do novo sólido não foi feito corretamente. O terceiro esboço, em vez de ser apoiado pela face superior do segundo bloco, aparece em um local estranho, com sua normal orientada para a direção X. Isso resulta em um bloco inválido, já que esse bloco seria desconectado do restante do corpo, o que não é permitido.
O problema parece ser que, quando o segundo esboço foi modificado, a face superior do segundo bloco foi renomeada de Face13
para Face14
. O terceiro esboço está anexado a Face13
como estava originalmente, mas como essa face agora está na lateral (e não no topo), o esboço segue sua orientação e agora está posicionado incorretamente.
![]() |
![]() |
7. Para corrigir o problema, o terceiro esboço deve ser mapeado novamente para a face superior. Selecione o esboço (Sketch002), clique nas reticências (três pontos) ao lado da propriedade DadosMap Mode e escolha novamente a face superior do segundo bloco. Em seguida, o esboço se move para a parte superior do sólido existente e o terceiro bloco é gerado sem problemas.
![]() |
![]() |
O remapeamento de um esboço dessa forma pode ser feito sempre que houver um erro de nomeação topológica; no entanto, isso pode ser tedioso se o modelo for complicado e houver muitos esboços que precisem ser ajustados.
Solução

O gráfico de dependência é uma ferramenta útil para observar as relações entre os diferentes corpos do documento. O uso do fluxo de trabalho de modelagem original revela a relação direta que existe entre os esboços e os blocos. Como em uma cadeia, é fácil ver que essa dependência direta estará sujeita a problemas de nomeação topológica se algum dos links da sequência for alterado.
Conforme explicado na página edição de recursos, uma solução para esse problema é oferecer suporte a esboços não em faces, mas nos planos principais da PartDesign Corpo Origin, ou em planos de referência anexados a esses planos principais. O uso de planos de referência para suportar um único esboço, conforme descrito abaixo, não é realmente necessário, pois o próprio esboço pode ser anexado diretamente a um plano principal e tem as mesmas opções de deslocamento que um plano de referência. Mas o uso de planos de referência pode fazer sentido ao posicionar vários esboços.
1. Select the origin of the PartDesign Body and make sure that it is visible. Then select the XY plane, and click on PartDesign Plane. In the attachment offset dialog, give it an offset in the Z direction so that the datum plane is coplanar with the top face of the first pad.
2. Repita o processo, mas, desta vez, adicione um deslocamento maior para que o segundo plano de referência fique coplanar com a face superior do segundo bloco.
![]() |
![]() |
3. Select the second sketch, click on the ellipsis next to the DadosMap Mode property, and then select the first datum plane. The datum plane is already offset from the body's XY plane, so no further Z offset is required for the sketch.
4. Repeat the process with the third sketch, and select the second datum plane as support. Again, no further Z offset is necessary.
5. The dependency graph now shows that the sketches and pads are supported by the datum planes. This model is more stable as each sketch can be modified essentially independently from each other.
6. Double click the second sketch and modify the shape. The second pad should update immediately without causing topological problems with the third sketch and the third pad.
7. In fact, every sketch can be modified without interfering with each other's pads. As long as the pads have sufficient extrusion length, so that they touch and form a contiguous solid, the entire body will be valid.
Vantagens e desvantagens
Adicionar objetos de datum é mais trabalhoso para o usuário, mas, em última análise, produz modelos mais estáveis que estão menos sujeitos ao problema de nomeação topológica.
Naturalmente, os objetos de referência podem ser criados antes de qualquer esboço ser desenhado e os blocos serem produzidos. Isso pode ser útil para visualizar a forma e as dimensões aproximadas do corpo final.
Datum planes can also be based on other datum planes. This creates a chain of dependencies that could also result in topological problems; however, since datum planes are very simple objects, the risks of having these issues is less than if the face of a solid object is used as support.
Datum objects, points, lines, planes, and coordinate systems, may also be useful as reference geometry, that is, as visual aids to show the important features in the model, even if no sketch is directly attached to them.
Algoritmo de nomeação topológica
O algoritmo de nomeação topológica do Realthunder, selecionado para reduzir o impacto desse problema, foi amplamente descrito como “consertando o problema de nomeação topológica”, o que induziu involuntariamente muitos usuários a pensar que não será mais útil usar técnicas como datums, posicionamento explícito de esboços e Edição de recursos para tornar os modelos mais estáveis. O algoritmo não se destina a corrigir todas as falhas introduzidas pela ambiguidade de nomes topológicos. Em vez disso, ele tem três objetivos.
- O primeiro e mais importante objetivo é, sempre que possível, identificar referências quebradas de alterações topológicas e exibir um erro para o usuário. Em vez de ter de trabalhar em uma série de operações para encontrar a primeira operação que diverge da intenção do projeto, a operação que altera os nomes normalmente será sinalizada com um erro, o que facilita muito a correção manual de problemas de modelo introduzidos por alterações em operações ou parâmetros.
- Às vezes, o FreeCAD poderá identificar uma “provável” correção para uma referência quebrada, de modo que, quando o usuário estiver corrigindo manualmente a referência quebrada sinalizada, um candidato será apresentado para que ele aceite ou altere. Um exemplo comum disso são as operações de acabamento, como filetes e chanfros, em que o usuário pode ter de editar a operação e aceitar a seleção do recurso de substituição proposto ou alterá-lo para corrigi-lo.
- Em alguns casos, o FreeCAD poderá resolver automaticamente a referência quebrada, pois há informações suficientes sobre a referência armazenadas para que se tenha alta confiança de que a substituição está correta. Por exemplo, ao esboçar diretamente em uma face, o algoritmo frequentemente (mas nem sempre) reparará corretamente a referência à face quando a geometria subjacente for alterada parametricamente. (Ao alterar a estrutura, por exemplo, adicionando ou excluindo operações no meio de um corpo de desenho de peça, esse tipo de reparo automático será menos provável). No entanto, o FreeCAD fará isso somente com alta confiança na exatidão do reparo, pois um reparo automático incorreto pode reintroduzir o problema de ter de procurar onde o problema foi introduzido para reparar um modelo após uma modificação. “Primeiro, não cause danos”.
A meta para o FreeCAD 1.0 é que a implementação desse algoritmo na versão oficial do FreeCAD tenha atingido a paridade de recursos com a bifurcação “Linkstage 3” de Realthunder, onde ele originalmente desenvolveu o algoritmo, no momento em que o trabalho de integração foi iniciado. Há novos recursos do FreeCAD que poderiam usar o algoritmo, mas ainda não o fazem, e sempre haverá mais oportunidades de adicionar correções candidatas e reparos automáticos. O trabalho inicial forneceu uma “estrutura” a ser usada para esses aprimoramentos adicionais ao longo do tempo, tanto no FreeCAD principal quanto nos Addons.
Links
- PartDesign Fillet - Topological naming
- Topological Naming, My Take: a possible solution, by realthunder.
- Topological Naming Project: idea to solve the problem, by ickby.
- Topological data scripting
- Feature editing: contains alternate advice for stable modelling techniques.
- Clarifying and expanding "Topological Naming Problem" documentation: Clarifying expectations for Realthunder's topological naming algorithm selected for FreeCAD 1.0.
Vídeos
- Why do my FreeCAD models break? - "Topological Naming Problem": A Video explanation of the underlying issues of Topological naming problem
- FreeCAD Is Fundamentally Broken! - Now what... Help Me Decide...: A Maker Tales Video

- Getting started
- Installation: Download, Windows, Linux, Mac, Additional components, Docker, AppImage, Ubuntu Snap
- Basics: About FreeCAD, Interface, Mouse navigation, Selection methods, Object name, Preferences, Workbenches, Document structure, Properties, Help FreeCAD, Donate
- Help: Tutorials, Video tutorials
- Workbenches: Std Base, Assembly, BIM, CAM, Draft, FEM, Inspection, Material, Mesh, OpenSCAD, Part, PartDesign, Points, Reverse Engineering, Robot, Sketcher, Spreadsheet, Surface, TechDraw, Test Framework
- Hubs: User hub, Power users hub, Developer hub
- Pages: Insert Default Page, Insert Page using Template, Update template fields, Redraw Page, Print All Pages, Export Page as SVG, Export Page as DXF
- Views:
- TechDraw views: Insert View, Insert Broken View, Insert Section View, Insert Complex Section View, Insert Detail View, Insert Projection Group, Insert Clip Group, Insert SVG Symbol, Insert Bitmap Image, Share View, Turn View Frames On/Off, Project Shape
- Views from other workbenches: Insert Active View, Insert Draft Workbench Object, Insert BIM Workbench Object, Insert Spreadsheet View
- Stacking: Move view to top of stack, Move view to bottom of stack, Move view up one level, Move view down one level
- Dimensions: Insert Dimension, Insert Length Dimension, Insert Horizontal Dimension, Insert Vertical Dimension, Insert Radius Dimension, Insert Diameter Dimension, Insert Angle Dimension, Insert 3-Point Angle Dimension, Insert Area Annotation, Create Arc Length Dimension, Insert Horizontal Extent Dimension, Insert Vertical Extent Dimension, Create Horizontal Chain Dimensions, Create Vertical Chain Dimensions, Create Oblique Chain Dimensions, Create Horizontal Coordinate Dimensions, Create Vertical Coordinate Dimensions, Create Oblique Coordinate Dimensions, Create Horizontal Chamfer Dimension, Create Vertical Chamfer Dimension, Insert Balloon Annotation, Insert Axonometric Length Dimension, Insert Landmark Dimension, Dimension Repair, Link Dimension to 3D Geometry
- Hatching: Hatch Face using Image File, Apply Geometric Hatch to Face,
- Annotations: Insert Annotation, Add Leaderline to View, Insert Rich Text Annotation, Add Cosmetic Vertex, Add Midpoint Vertices, Add Quadrant Vertices, Add Centerline to Faces, Add Centerline between 2 Lines, Add Centerline between 2 Points, Add Cosmetic Line Through 2 points, Add Cosmetic Circle, Change Appearance of Lines, Show/Hide Invisible Edges, Add Welding Information to Leader, Add Surface Finish Symbol, Add Hole or Shaft Tolerances
- Extensions:
- Attributes and modifications: Select Line Attributes, Cascade Spacing and Delta Distance, Change Line Attributes, Extend Line, Shorten Line, Lock/Unlock View, Position Section View, Position Horizontal Chain Dimensions, Position Vertical Chain Dimensions, Position Oblique Chain Dimensions, Cascade Horizontal Dimensions, Cascade Vertical Dimensions, Cascade Oblique Dimensions, Calculate the area of selected faces, Calculate the arc length of selected edges, Customize format label
- Centerlines and threading: Add Circle Centerlines, Add Bolt Circle Centerlines, Add Cosmetic Thread Hole Side View, Add Cosmetic Thread Hole Bottom View, Add Cosmetic Thread Bolt Side View, Add Cosmetic Thread Bolt Bottom View, Add Cosmetic Intersection Vertex(es), Add an offset vertex, Add Cosmetic Circle, Add Cosmetic Arc, Add Cosmetic Circle 3 Points, Add Cosmetic Parallel Line, Add Cosmetic Perpendicular Line
- Dimensions: Insert '⌀' Prefix, Insert '□' Prefix, Insert 'n×' Prefix, Remove Prefix, Increase Decimal Places, Decrease Decimal Places
- Miscellaneous: Remove Cosmetic Object
- Additional: Line Groups, Templates, Hatching, Geometric dimensioning and tolerancing, Preferences
- Structure tools: Part, Group
- Helper tools: Create body, Create sketch, Attach sketch, Edit sketch, Validate sketch, Check geometry, Create a shape binder, Create a sub-object(s) shape binder, Create a clone, Create a datum plane, Create a datum line, Create a datum point, Create a local coordinate system
- Modeling tools:
- Additive tools: Pad, Revolution, Additive loft, Additive pipe, Additive helix, Additive box, Additive cylinder, Additive sphere, Additive cone, Additive ellipsoid, Additive torus, Additive prism, Additive wedge
- Subtractive tools: Pocket, Hole, Groove, Subtractive loft, Subtractive pipe, Subtractive helix, Subtractive box, Subtractive cylinder, Subtractive sphere, Subtractive cone, Subtractive ellipsoid, Subtractive torus, Subtractive prism, Subtractive wedge
- Boolean: Boolean operation
- Dress-up tools: Fillet, Chamfer, Draft, Thickness
- Transformation tools: Mirrored, Linear Pattern, Polar Pattern, Create MultiTransform, Scaled
- Extras: Sprocket, Involute gear, Shaft design wizard
- Context menu: Set tip, Move object to other body, Move object after other object, Appearance, Color per face
- Preferences: Preferences, Fine tuning
- Primitives: Box, Cylinder, Sphere, Cone, Torus, Tube, Create primitives, Shape builder
- Creation and modification: Create sketch, Extrude, Revolve, Mirror, Scale, Fillet, Chamfer, Make face from wires, Ruled Surface, Loft, Sweep, Section, Cross sections, 3D Offset, 2D Offset, Thickness, Projection on surface, Color per face
- Boolean: Make compound, Explode compound, Compound Filter, Boolean, Cut, Union, Intersection, Connect objects, Embed object, Cutout for object, Boolean fragments, Slice apart, Slice to compound, Boolean XOR, Check geometry, Defeaturing
- Other tools: Import CAD file, Export CAD file, Box selection, Create shape from mesh, Create points object from geometry, Convert to solid, Reverse shapes, Create simple copy, Create transformed copy, Create shape element copy, Refine shape, Attachment
- Preferences: Preferences, Fine tuning