mindmap.mindmap module

class mindmap.mindmap.MindmapDocument(charttype: str = 'auto', turbo_mode: bool = False, inline_editing_mode: bool = False, mermaid_mode: bool = True)

Bases: object

__init__(charttype: str = 'auto', turbo_mode: bool = False, inline_editing_mode: bool = False, mermaid_mode: bool = True)

Initialize a MindmapDocument instance which automates MindManager operations.

Parameters:

  • charttype (str) – The type of chart to be used (orgchart, radial, auto).

  • turbo_mode (bool) – Flag for enabling turbo mode -> use only text.

  • inline_editing_mode (bool) – Flag for enabling inline editing mode.

  • mermaid_mode (bool) – Flag for enabling mermaid mode.

check_parent_exists(topic_guid, this_guid, visited=None)

Recursively check if a parent-child relationship exists between topics.

Parameters:

  • topic_guid (str) – The GUID of the topic to check.

  • this_guid (str) – The GUID that might be a parent of the topic.

  • visited (set, optional) – Set of visited GUIDs to avoid infinite recursion.

Returns:

True if the parent-child relationship exists, False otherwise.

Return type:

bool

clone_mindmap_topic(mindmap_topic, subtopics: list[MindmapTopic] = None, parent=None)

Clone a MindmapTopic instance including its subtopics.

Parameters:

  • mindmap_topic (MindmapTopic) – The topic to clone.

  • subtopics (list[MindmapTopic], optional) – A list of subtopics to clone.

  • parent – The parent for the cloned topic.

Returns:

A new instance that is a clone of the given topic.

Return type:

MindmapTopic

count_parent_and_child_occurrences(mindmap_topic, guid_counts, visited=None)

Recursively count the occurrences of parent and child relationships for each topic.

Parameters:

  • mindmap_topic (MindmapTopic) – The current topic in the mindmap.

  • guid_counts (dict) – Dictionary to store counts with topic GUID as keys.

  • visited (set) – Set of visited topic GUIDs to avoid infinite recursion.

create_mindmap(verbose=False)

Create a MindManager mindmap document from the internal MindmapTopic structure. This includes counting occurrences, extracting tags/icons, and setting up relationships and links.

Parameters:

verbose (bool) – (Optional) Enable verbose output.

create_mindmap_and_finalize()

Create the mindmap document and finalize it.

finalize()

Finalize the mindmap document by ensuring the maximum topic level is set, then calling MindManager’s finalize.

get_grounding_information()

Extract grounding information from the mindmap, including the central topic and selected subtopics.

Returns:

(top_most_topic, subtopics) where top_most_topic is the central topic or a concatenated string

of non-selected topics, and subtopics is a comma-separated string of selected subtopics.

Return type:

tuple

get_library_folder()

Get the library folder used by MindManager.

Returns:

The path to the library folder.

get_map_icons_and_fix_refs_from_mindmap(mindmap, map_icons: list[MindmapIcon], visited=None)

Extract icons from mindmap topics and fix their references if needed.

Parameters:

  • mindmap (MindmapTopic) – The current topic in the mindmap.

  • map_icons (list[MindmapIcon]) – List to collect unique icons.

  • visited (set) – Set of visited topic GUIDs to avoid infinite recursion.

get_max_topic_level(mindmap_topic, max_topic_level=0, visited=None)

Recursively compute the maximum topic level within the mind map.

Parameters:

  • mindmap_topic (MindmapTopic) – The current topic to evaluate.

  • max_topic_level (int) – The current maximum level found.

  • visited (set) – Set of visited topic GUIDs to avoid infinite recursion.

Returns:

The highest topic level found in the mindmap.

Return type:

int

get_mindmap(topic=None, mode='full')

Retrieve the mind map structure from the currently open MindManager document.

Parameters:

  • topic – (Optional) A specific topic from which to start building the mindmap. If not provided, the central topic is used.

  • mode (str) – The mode to use to gather attributes (full=all attributes, content=text+rtf+notes, text=text only).

Returns:

True if the mind map was successfully retrieved, otherwise False.

Return type:

bool

get_mindmap_topic_from_topic(topic, parent_topic=None, mode='full')

Recursively convert a MindManager topic into a MindmapTopic object.

Parameters:

  • topic – The current MindManager topic to convert.

  • parent_topic (MindmapTopic) – The parent MindmapTopic, if any.

  • mode (str) – The mode to use to gather attributes (full=all attributes, content=text+rtf+notes, text=text only).

Returns:

The converted topic with its subtopics.

Return type:

MindmapTopic

get_parent_topic(topic)

Retrieve the parent topic for a given MindManager topic.

Parameters:

topic – The current topic from which to get the parent.

Returns:

The parent topic wrapped as a MindmapTopic, or None if at the root.

Return type:

MindmapTopic or None

get_parents_from_mindmap(mindmap, parents, visited=None)

Build a dictionary mapping subtopic GUIDs to their parent’s GUID.

Parameters:

  • mindmap (MindmapTopic) – The current topic in the mindmap.

  • parents (dict) – Dictionary to store parent-child GUID mappings.

  • visited (set) – Set of visited topic GUIDs to avoid infinite recursion.

get_relationships_from_mindmap(mindmap, references, visited=None)

Recursively extract relationships (references) from the mindmap.

Parameters:

  • mindmap (MindmapTopic) – The current topic in the mindmap.

  • references (list[MindmapReference]) – List to collect the relationships.

  • visited (set) – Set of visited topic GUIDs to avoid infinite recursion.

get_selection()

Retrieve the currently selected topics in the MindManager document.

Returns:

A list of MindmapTopic instances representing the selection.

Return type:

list[MindmapTopic]

get_tags_from_mindmap(mindmap, tags, visited=None)

Recursively collect unique tags from the mindmap.

Parameters:

  • mindmap (MindmapTopic) – The current topic in the mindmap.

  • tags (list[str]) – List to collect tag texts.

  • visited (set) – Set of visited topic GUIDs to avoid infinite recursion.

Recursively extract topic links from the mindmap.

Parameters:

  • mindmap (MindmapTopic) – The current topic in the mindmap.

  • links (list[MindmapReference]) – List to collect topic links as MindmapReference objects.

  • visited (set) – Set of visited topic GUIDs to avoid infinite recursion.

get_topic_texts_from_selection(mindmap_topics)

Extract topic texts, levels, and GUIDs from selected topics.

Parameters:

mindmap_topics (list[MindmapTopic]) – List of topics to process.

Returns:

(list of topic texts, list of topic levels, list of topic GUIDs, bool indicating if the central topic is selected)

Return type:

tuple

set_background_image(image_path)

Set the background image for the MindManager document.

Parameters:

image_path (str) – The file path to the background image.

set_topic_from_mindmap_topic(topic, mindmap_topic, map_icons, done=None, done_global=None, level=0)

Create or update a MindManager topic from a MindmapTopic instance recursively.

Parameters:

  • topic – The current MindManager topic to update.

  • mindmap_topic (MindmapTopic) – The source MindmapTopic data.

  • map_icons (list[MindmapIcon]) – List of map icons to use.

  • done (dict, optional) – Dictionary tracking processed topics at current level.

  • done_global (dict, optional) – Global dictionary for tracking duplicate processing.

  • level (int) – Current hierarchical level.

Returns:

The processed MindmapTopic.

Return type:

MindmapTopic

update_done(topic_guid, mindmap_topic, level, done, done_global)

Update tracking dictionaries for processed topics and create duplicate links/tags.

Parameters:

  • topic_guid (str) – The GUID of the current topic in MindManager.

  • mindmap_topic (MindmapTopic) – The MindmapTopic being processed.

  • level (int) – The current level in the topic hierarchy.

  • done (dict) – Dictionary tracking topics processed at a given level.

  • done_global (dict) – Global dictionary tracking processed topics for duplicate detection.

class mindmap.mindmap.MindmapIcon(text: str = '', is_stock_icon=True, index: int = 1, signature: str = '', path: str = '', group: str = '')

Bases: object

__init__(text: str = '', is_stock_icon=True, index: int = 1, signature: str = '', path: str = '', group: str = '')

Initialize a MindmapIcon instance.

Parameters:

  • text (str) – The display text for the icon.

  • is_stock_icon (bool) – Flag indicating if the icon is a stock icon.

  • index (int) – The index of a stock icon.

  • signature (str) – A unique signature for the icon.

  • path (str) – File path to the icon if it is custom.

  • group (str) – The group/category of the icon.

class mindmap.mindmap.MindmapImage(text: str = '')

Bases: object

__init__(text: str = '')

Initialize a MindmapImage instance.

Parameters:

text (str) – Path to the image.

Bases: object

__init__(text: str = '', url: str = '', guid: str = '')

Initialize a MindmapLink instance.

Parameters:

  • text (str) – The display text for the link.

  • url (str) – The URL that the link points to.

  • guid (str) – A unique identifier for the link.

class mindmap.mindmap.MindmapNotes(text: str = '', xhtml: str = '', rtf: str = '')

Bases: object

__init__(text: str = '', xhtml: str = '', rtf: str = '')

Initialize a MindmapNotes instance.

Parameters:

  • text (str) – Plain text version of the notes.

  • xhtml (str) – XHTML formatted notes.

  • rtf (str) – RTF formatted notes.

class mindmap.mindmap.MindmapReference(guid_1: str = '', guid_2: str = '', direction: int = 1, label: str = '')

Bases: object

__init__(guid_1: str = '', guid_2: str = '', direction: int = 1, label: str = '')

Initialize a MindmapReference (relationship) instance.

Parameters:

  • guid_1 (str) – The GUID of the first topic.

  • guid_2 (str) – The GUID of the second topic.

  • direction (int) – The direction of the reference (1 indicates a standard direction).

  • label (str) – A label for the relationship.

class mindmap.mindmap.MindmapTag(text: str = '')

Bases: object

__init__(text: str = '')

Initialize a MindmapTag instance.

Parameters:

text (str) – The text representing the tag.

class mindmap.mindmap.MindmapTopic(guid: str = '', text: str = '', rtf: str = '', level: int = 0, selected: bool = False, parent: MindmapTopic = None, subtopics: list[MindmapTopic] = None, links: list[MindmapLink] = None, image: MindmapImage = None, icons: list[MindmapIcon] = None, notes: MindmapNotes = None, tags: list[MindmapTag] = None, references: list[MindmapReference] = None)

Bases: object

__init__(guid: str = '', text: str = '', rtf: str = '', level: int = 0, selected: bool = False, parent: MindmapTopic = None, subtopics: list[MindmapTopic] = None, links: list[MindmapLink] = None, image: MindmapImage = None, icons: list[MindmapIcon] = None, notes: MindmapNotes = None, tags: list[MindmapTag] = None, references: list[MindmapReference] = None)

Initialize a MindmapTopic instance.

Parameters:

  • guid (str) – Unique identifier for the topic.

  • text (str) – The text content of the topic.

  • rtf (str) – RTF formatted text for the topic.

  • level (int) – The hierarchical level of the topic.

  • selected (bool) – Flag to indicate if the topic is selected.

  • parent (MindmapTopic) – The parent topic if any.

  • subtopics (list[MindmapTopic]) – List of subtopics.

  • links (list[MindmapLink]) – List of associated links.

  • image (MindmapImage) – Associated image object.

  • icons (list[MindmapIcon]) – List of associated icons.

  • notes (MindmapNotes) – Associated notes.

  • tags (list[MindmapTag]) – List of associated tags.

  • references (list[MindmapReference]) – List of associated relationships.

Source code for mindmap.py
  1import uuid
  2
  3import mindm.mindmanager as mm
  4
  5DUPLICATED_TAG = 'Duplicated'
  6DUPLICATE_LABEL = 'DUPLICATE'
  7
  8class MindmapLink:
  9    def __init__(self, text: str = '', url: str = '', guid: str = ''):
 10        """
 11        Initialize a MindmapLink instance.
 12
 13        Args:
 14            text (str): The display text for the link.
 15            url (str): The URL that the link points to.
 16            guid (str): A unique identifier for the link.
 17        """
 18        self.text = text
 19        self.url = url
 20        self.guid = guid
 21
 22class MindmapImage:
 23    def __init__(self, text: str = ''):
 24        """
 25        Initialize a MindmapImage instance.
 26
 27        Args:
 28            text (str): Path to the image.
 29        """
 30        self.text = text
 31
 32class MindmapNotes:
 33    def __init__(self, text: str = '', xhtml: str = '', rtf: str = ''):
 34        """
 35        Initialize a MindmapNotes instance.
 36
 37        Args:
 38            text (str): Plain text version of the notes.
 39            xhtml (str): XHTML formatted notes.
 40            rtf (str): RTF formatted notes.
 41        """
 42        self.text = text
 43        self.xhtml = xhtml
 44        self.rtf = rtf
 45
 46class MindmapIcon:
 47    def __init__(self, 
 48                 text: str = '', 
 49                 is_stock_icon=True, 
 50                 index: int = 1, 
 51                 signature: str = '', 
 52                 path: str = '',
 53                 group: str = ''):
 54        """
 55        Initialize a MindmapIcon instance.
 56
 57        Args:
 58            text (str): The display text for the icon.
 59            is_stock_icon (bool): Flag indicating if the icon is a stock icon.
 60            index (int): The index of a stock icon.
 61            signature (str): A unique signature for the icon.
 62            path (str): File path to the icon if it is custom.
 63            group (str): The group/category of the icon.
 64        """
 65        self.text = text
 66        self.is_stock_icon = is_stock_icon
 67        self.index = index
 68        self.signature = signature
 69        self.path = path
 70        self.group = group
 71
 72class MindmapTag:
 73    def __init__(self, text: str = ''):
 74        """
 75        Initialize a MindmapTag instance.
 76
 77        Args:
 78            text (str): The text representing the tag.
 79        """
 80        self.text = text
 81
 82class MindmapReference:
 83    def __init__(self, 
 84                 guid_1: str = '', 
 85                 guid_2: str = '', 
 86                 direction: int = 1, 
 87                 label: str = ''):
 88        """
 89        Initialize a MindmapReference (relationship) instance.
 90
 91        Args:
 92            guid_1 (str): The GUID of the first topic.
 93            guid_2 (str): The GUID of the second topic.
 94            direction (int): The direction of the reference (1 indicates a standard direction).
 95            label (str): A label for the relationship.
 96        """
 97        self.guid_1 = guid_1
 98        self.guid_2 = guid_2
 99        self.direction = direction
100        self.label = label
101
102class MindmapTopic:
103    def __init__(self,
104                 guid: str = '',
105                 text: str = '',
106                 rtf: str = '',
107                 level: int = 0,
108                 selected: bool = False,
109                 parent: 'MindmapTopic' = None,
110                 subtopics: list['MindmapTopic'] = None,
111                 links: list['MindmapLink'] = None,
112                 image: 'MindmapImage' = None,
113                 icons: list['MindmapIcon'] = None,
114                 notes: 'MindmapNotes' = None,
115                 tags: list['MindmapTag'] = None,
116                 references: list['MindmapReference'] = None):
117        """
118        Initialize a MindmapTopic instance.
119
120        Args:
121            guid (str): Unique identifier for the topic.
122            text (str): The text content of the topic.
123            rtf (str): RTF formatted text for the topic.
124            level (int): The hierarchical level of the topic.
125            selected (bool): Flag to indicate if the topic is selected.
126            parent (MindmapTopic): The parent topic if any.
127            subtopics (list[MindmapTopic]): List of subtopics.
128            links (list[MindmapLink]): List of associated links.
129            image (MindmapImage): Associated image object.
130            icons (list[MindmapIcon]): List of associated icons.
131            notes (MindmapNotes): Associated notes.
132            tags (list[MindmapTag]): List of associated tags.
133            references (list[MindmapReference]): List of associated relationships.
134        """
135        self.guid = guid
136        self.text = text.replace('"', '`').replace("'", "`").replace("\r", "").replace("\n", "")
137        self.rtf = rtf
138        self.level = level
139        self.selected = selected
140        self.parent = parent
141        self.links = links if links is not None else []
142        self.image = image
143        self.icons = icons if icons is not None else []
144        self.notes = notes
145        self.tags = tags if tags is not None else []
146        self.references = references if references is not None else []
147        self.subtopics = subtopics if subtopics is not None else []
148
149
150class MindmapDocument:
151    def __init__(self, charttype: str = 'auto', turbo_mode: bool = False, inline_editing_mode: bool = False, mermaid_mode: bool = True):
152        """
153        Initialize a MindmapDocument instance which automates MindManager operations.
154
155        Args:
156            charttype (str): The type of chart to be used (orgchart, radial, auto).
157            turbo_mode (bool): Flag for enabling turbo mode -> use only text.
158            inline_editing_mode (bool): Flag for enabling inline editing mode.
159            mermaid_mode (bool): Flag for enabling mermaid mode.
160        """
161        self.charttype: str = charttype
162        self.turbo_mode: bool = turbo_mode
163        self.inline_editing_mode: bool = inline_editing_mode
164        self.mermaid_mode: bool = mermaid_mode
165        self.mindmap: 'MindmapTopic' = None
166        self.central_topic_selected: bool = False
167        self.selected_topic_texts: list[str] = []
168        self.selected_topic_levels: list[int] = []
169        self.selected_topic_ids: list[str] = []
170        self.max_topic_level: int = 0
171
172        self.mindm = mm.Mindmanager(charttype)
173
174    def get_mindmap(self, topic=None, mode='full'):
175        """
176        Retrieve the mind map structure from the currently open MindManager document.
177
178        Args:
179            topic: (Optional) A specific topic from which to start building the mindmap.
180                   If not provided, the central topic is used.
181            mode (str): The mode to use to gather attributes (full=all attributes, content=text+rtf+notes, text=text only).
182
183        Returns:
184            bool: True if the mind map was successfully retrieved, otherwise False.
185        """
186        if not self.mindm.document_exists():
187            print("No document found. Please open MindManager with a document.")    
188            return False
189
190        if topic is None:
191            topic = self.mindm.get_central_topic()
192        
193        # Build the mindmap topic structure from the provided topic
194        mindmap = self.get_mindmap_topic_from_topic(topic, mode=mode)
195
196        # Retrieve the current selection information
197        selection = self.get_selection()
198        selected_topic_texts, selected_topic_levels, selected_topic_ids, central_topic_selected = self.get_topic_texts_from_selection(selection)
199        self.central_topic_selected = central_topic_selected
200        self.selected_topic_texts = selected_topic_texts
201        self.selected_topic_levels = selected_topic_levels
202        self.selected_topic_ids = selected_topic_ids
203        self.max_topic_level = self.get_max_topic_level(mindmap)
204        self.mindmap = mindmap
205        return True
206    
207    def get_max_topic_level(self, mindmap_topic, max_topic_level=0, visited=None):
208        """
209        Recursively compute the maximum topic level within the mind map.
210
211        Args:
212            mindmap_topic (MindmapTopic): The current topic to evaluate.
213            max_topic_level (int): The current maximum level found.
214            visited (set): Set of visited topic GUIDs to avoid infinite recursion.
215
216        Returns:
217            int: The highest topic level found in the mindmap.
218        """
219        if visited is None:
220            visited = set()
221        if mindmap_topic.guid in visited:
222            return max_topic_level
223        visited.add(mindmap_topic.guid)
224        for subtopic in mindmap_topic.subtopics:
225            if subtopic.level > max_topic_level:
226                max_topic_level = subtopic.level
227            max_topic_level = self.get_max_topic_level(subtopic, max_topic_level, visited)
228        return max_topic_level
229
230    def get_parent_topic(self, topic):
231        """
232        Retrieve the parent topic for a given MindManager topic.
233
234        Args:
235            topic: The current topic from which to get the parent.
236
237        Returns:
238            MindmapTopic or None: The parent topic wrapped as a MindmapTopic, or None if at the root.
239        """
240        topic_level = self.mindm.get_level_from_topic(topic)
241        if topic_level == 0:
242            return None
243        parent_topic = self.mindm.get_parent_from_topic(topic)
244        parent_mindmap_topic = MindmapTopic(
245            guid=self.mindm.get_guid_from_topic(parent_topic),
246            text=self.mindm.get_text_from_topic(parent_topic), 
247            level=self.mindm.get_level_from_topic(parent_topic),
248            parent=self.get_parent_topic(parent_topic),
249        )
250        return parent_mindmap_topic
251
252    def get_selection(self):
253        """
254        Retrieve the currently selected topics in the MindManager document.
255
256        Returns:
257            list[MindmapTopic]: A list of MindmapTopic instances representing the selection.
258        """
259        selection = self.mindm.get_selection()
260        mindmap_topics = []
261        for topic in selection:
262            level = self.mindm.get_level_from_topic(topic)
263            mindmap_topic = MindmapTopic(
264                guid=self.mindm.get_guid_from_topic(topic),
265                text=self.mindm.get_text_from_topic(topic), 
266                level=level,
267                parent=self.get_parent_topic(topic),
268                selected=True,
269            )
270            mindmap_topics.append(mindmap_topic)
271        return mindmap_topics
272
273    def get_mindmap_topic_from_topic(self, topic, parent_topic=None, mode='full'):
274        """
275        Recursively convert a MindManager topic into a MindmapTopic object.
276
277        Args:
278            topic: The current MindManager topic to convert.
279            parent_topic (MindmapTopic): The parent MindmapTopic, if any.
280            mode (str): The mode to use to gather attributes (full=all attributes, content=text+rtf+notes, text=text only).
281
282        Returns:
283            MindmapTopic: The converted topic with its subtopics.
284        """
285        mindmap_topic = MindmapTopic(
286            guid=self.mindm.get_guid_from_topic(topic),
287            text=self.mindm.get_text_from_topic(topic),
288            rtf=self.mindm.get_title_from_topic(topic),
289            level=self.mindm.get_level_from_topic(topic),
290            parent=parent_topic
291        )
292
293        if mode == 'full':
294            mindmap_topic.links = self.mindm.get_links_from_topic(topic)
295            mindmap_topic.image = self.mindm.get_image_from_topic(topic)
296            mindmap_topic.icons = self.mindm.get_icons_from_topic(topic)
297            mindmap_topic.notes = self.mindm.get_notes_from_topic(topic)
298            mindmap_topic.tags = self.mindm.get_tags_from_topic(topic)
299            mindmap_topic.references = self.mindm.get_references_from_topic(topic)
300
301        if mode == 'content':
302            mindmap_topic.notes = self.mindm.get_notes_from_topic(topic)
303
304        subtopics = self.mindm.get_subtopics_from_topic(topic)
305        mindmap_subtopics = []
306        for subtopic in subtopics:
307            child = self.get_mindmap_topic_from_topic(subtopic, parent_topic=mindmap_topic, mode=mode)
308            mindmap_subtopics.append(child)
309        mindmap_topic.subtopics = mindmap_subtopics
310        return mindmap_topic 
311
312    def get_relationships_from_mindmap(self, mindmap, references, visited=None):
313        """
314        Recursively extract relationships (references) from the mindmap.
315
316        Args:
317            mindmap (MindmapTopic): The current topic in the mindmap.
318            references (list[MindmapReference]): List to collect the relationships.
319            visited (set): Set of visited topic GUIDs to avoid infinite recursion.
320        """
321        if visited is None:
322            visited = set()
323        if mindmap.guid in visited:
324            return
325        visited.add(mindmap.guid)
326        for reference in mindmap.references:
327            if reference.direction == 1:
328                references.append(MindmapReference(
329                    guid_1=reference.guid_1,
330                    guid_2=reference.guid_2,
331                    direction=reference.direction,
332                    label=reference.label
333                ))
334        for subtopic in mindmap.subtopics:
335            self.get_relationships_from_mindmap(subtopic, references, visited)
336
337    def get_topic_links_from_mindmap(self, mindmap, links, visited=None):
338        """
339        Recursively extract topic links from the mindmap.
340
341        Args:
342            mindmap (MindmapTopic): The current topic in the mindmap.
343            links (list[MindmapReference]): List to collect topic links as MindmapReference objects.
344            visited (set): Set of visited topic GUIDs to avoid infinite recursion.
345        """
346        if visited is None:
347            visited = set()
348        if mindmap.guid in visited:
349            return
350        visited.add(mindmap.guid)
351        for link in mindmap.links:
352            if link.guid != '':
353                links.append(MindmapReference(
354                    guid_1=mindmap.guid, 
355                    guid_2=link.guid, 
356                    direction=1, 
357                    label=link.text
358                ))
359        for subtopic in mindmap.subtopics:
360            self.get_topic_links_from_mindmap(subtopic, links, visited)
361
362    def get_tags_from_mindmap(self, mindmap, tags, visited=None):
363        """
364        Recursively collect unique tags from the mindmap.
365
366        Args:
367            mindmap (MindmapTopic): The current topic in the mindmap.
368            tags (list[str]): List to collect tag texts.
369            visited (set): Set of visited topic GUIDs to avoid infinite recursion.
370        """
371        if visited is None:
372            visited = set()
373        if mindmap.guid in visited:
374            return
375        visited.add(mindmap.guid)
376        for tag in mindmap.tags:
377            if tag.text != '' and tag.text not in tags:
378                tags.append(tag.text)
379        for subtopic in mindmap.subtopics:
380            self.get_tags_from_mindmap(subtopic, tags, visited)
381
382    def get_parents_from_mindmap(self, mindmap, parents, visited=None):
383        """
384        Build a dictionary mapping subtopic GUIDs to their parent's GUID.
385
386        Args:
387            mindmap (MindmapTopic): The current topic in the mindmap.
388            parents (dict): Dictionary to store parent-child GUID mappings.
389            visited (set): Set of visited topic GUIDs to avoid infinite recursion.
390        """
391        if visited is None:
392            visited = set()
393        if mindmap.guid in visited:
394            return
395        visited.add(mindmap.guid)
396        for subtopic in mindmap.subtopics:
397            if subtopic.guid not in parents:
398                parents[subtopic.guid] = mindmap.guid
399                self.get_parents_from_mindmap(subtopic, parents, visited)
400        return
401
402    def get_map_icons_and_fix_refs_from_mindmap(self, mindmap, map_icons: list['MindmapIcon'], visited=None):
403        """
404        Extract icons from mindmap topics and fix their references if needed.
405
406        Args:
407            mindmap (MindmapTopic): The current topic in the mindmap.
408            map_icons (list[MindmapIcon]): List to collect unique icons.
409            visited (set): Set of visited topic GUIDs to avoid infinite recursion.
410        """
411        if visited is None:
412            visited = set()
413        if mindmap.guid in visited:
414            return
415        visited.add(mindmap.guid)
416        
417        for i, topic_icon_ref in enumerate(mindmap.icons):
418            # Only process non-stock icons belonging to the 'Types' group
419            if not topic_icon_ref.is_stock_icon and topic_icon_ref.group == 'Types':
420                found = False
421                for map_icon in map_icons:
422                    if map_icon.signature == topic_icon_ref.signature:
423                        found = True
424                        new_icon = map_icon
425                        break
426                if not found:
427                    new_icon = MindmapIcon(
428                        text=topic_icon_ref.text, 
429                        index=topic_icon_ref.index,
430                        is_stock_icon=topic_icon_ref.is_stock_icon, 
431                        path=topic_icon_ref.path,
432                        signature=topic_icon_ref.signature,
433                        group=topic_icon_ref.group)                
434                    map_icons.append(new_icon)
435                mindmap.icons[i] = new_icon
436        for subtopic in mindmap.subtopics:
437            self.get_map_icons_and_fix_refs_from_mindmap(subtopic, map_icons, visited)
438
439    def count_parent_and_child_occurrences(self, mindmap_topic, guid_counts, visited=None):
440        """
441        Recursively count the occurrences of parent and child relationships for each topic.
442
443        Args:
444            mindmap_topic (MindmapTopic): The current topic in the mindmap.
445            guid_counts (dict): Dictionary to store counts with topic GUID as keys.
446            visited (set): Set of visited topic GUIDs to avoid infinite recursion.
447        """
448        if visited is None:
449            visited = set()
450        if str(mindmap_topic.guid) == '':
451            mindmap_topic.guid = str(uuid.uuid4())
452        if mindmap_topic.guid not in visited:
453            visited.add(mindmap_topic.guid)
454            if mindmap_topic.guid not in guid_counts:
455                guid_counts[mindmap_topic.guid] = {'parent': 0, 'child': 0}
456            for subtopic in mindmap_topic.subtopics:
457                if mindmap_topic.guid:
458                    guid_counts[mindmap_topic.guid]['parent'] += 1
459                if subtopic.guid:
460                    if subtopic.guid not in guid_counts:
461                        guid_counts[subtopic.guid] = {'parent': 0, 'child': 0}
462                    guid_counts[subtopic.guid]['child'] += 1
463                self.count_parent_and_child_occurrences(subtopic, guid_counts, visited)
464
465    def get_topic_texts_from_selection(self, mindmap_topics):
466        """
467        Extract topic texts, levels, and GUIDs from selected topics.
468
469        Args:
470            mindmap_topics (list[MindmapTopic]): List of topics to process.
471
472        Returns:
473            tuple: (list of topic texts, list of topic levels, list of topic GUIDs, bool indicating if the central topic is selected)
474        """
475        topic_texts = []
476        topic_levels = []
477        topic_ids = []
478        central_topic_selected = False
479        for topic in mindmap_topics:
480            if topic.selected:
481                if topic.level > 0:
482                    topic_texts.append(topic.text)
483                    topic_levels.append(topic.level)
484                    topic_ids.append(topic.guid)
485                else:
486                    central_topic_selected = True
487        return topic_texts, topic_levels, topic_ids, central_topic_selected
488            
489    def clone_mindmap_topic(self, mindmap_topic, subtopics: list['MindmapTopic'] = None, parent=None):
490        """
491        Clone a MindmapTopic instance including its subtopics.
492
493        Args:
494            mindmap_topic (MindmapTopic): The topic to clone.
495            subtopics (list[MindmapTopic], optional): A list of subtopics to clone.
496            parent: The parent for the cloned topic.
497
498        Returns:
499            MindmapTopic: A new instance that is a clone of the given topic.
500        """
501        cloned_subtopics = []
502        if subtopics is not None:
503            for subtopic in subtopics:
504                cloned_subtopic = self.clone_mindmap_topic(subtopic)
505                cloned_subtopics.append(cloned_subtopic)
506        return MindmapTopic(
507            guid=mindmap_topic.guid,
508            text=mindmap_topic.text, 
509            rtf=mindmap_topic.rtf,
510            level=mindmap_topic.level,
511            parent=parent,
512            links=mindmap_topic.links,
513            image=mindmap_topic.image,
514            icons=mindmap_topic.icons,
515            notes=mindmap_topic.notes,
516            tags=mindmap_topic.tags,
517            subtopics=cloned_subtopics
518        )
519
520    def update_done(self, topic_guid, mindmap_topic, level, done, done_global):
521        """
522        Update tracking dictionaries for processed topics and create duplicate links/tags.
523
524        Args:
525            topic_guid (str): The GUID of the current topic in MindManager.
526            mindmap_topic (MindmapTopic): The MindmapTopic being processed.
527            level (int): The current level in the topic hierarchy.
528            done (dict): Dictionary tracking topics processed at a given level.
529            done_global (dict): Global dictionary tracking processed topics for duplicate detection.
530        """
531        if mindmap_topic.guid == '':
532            return
533        if level <= 1:
534            done = {}
535        elif level >= 2: 
536            done[mindmap_topic.guid] = [topic_guid] if mindmap_topic.guid not in done else done[mindmap_topic.guid] + [topic_guid]
537        if mindmap_topic.guid in done_global:
538            # Check for duplicate relationships and add links/tags accordingly.
539            if self.guid_counts[mindmap_topic.guid]['child'] < 11 and self.guid_counts[mindmap_topic.guid]['parent'] >= 0:
540                for i in range(len(done_global[mindmap_topic.guid])):
541                    link_from = topic_guid
542                    link_to = done_global[mindmap_topic.guid][i]
543                    self.mindm.add_topic_link(link_from, link_to, DUPLICATE_LABEL)
544                    self.mindm.add_topic_link(link_to, link_from, DUPLICATE_LABEL)
545                if len(done_global[mindmap_topic.guid]) == 1:
546                    self.mindm.add_tag_to_topic(topic=None, tag_text=DUPLICATED_TAG, topic_guid=done_global[mindmap_topic.guid][0])
547            self.mindm.add_tag_to_topic(topic=None, tag_text=DUPLICATED_TAG, topic_guid=topic_guid)
548            done_global[mindmap_topic.guid] = done_global[mindmap_topic.guid] + [topic_guid]
549        else:
550            done_global[mindmap_topic.guid] = [topic_guid]
551
552    def set_topic_from_mindmap_topic(self, topic, mindmap_topic, map_icons, done=None, done_global=None, level=0):
553        """
554        Create or update a MindManager topic from a MindmapTopic instance recursively.
555
556        Args:
557            topic: The current MindManager topic to update.
558            mindmap_topic (MindmapTopic): The source MindmapTopic data.
559            map_icons (list[MindmapIcon]): List of map icons to use.
560            done (dict, optional): Dictionary tracking processed topics at current level.
561            done_global (dict, optional): Global dictionary for tracking duplicate processing.
562            level (int): Current hierarchical level.
563            
564        Returns:
565            MindmapTopic: The processed MindmapTopic.
566        """
567        if done is None:
568            done = {}
569        if done_global is None:
570            done_global = {}
571        try:
572            if self.turbo_mode:
573                topic_guid = self.mindm.get_guid_from_topic(topic)
574                self.update_done(topic_guid, mindmap_topic, level, done, done_global)
575                for subtopic in mindmap_topic.subtopics:
576                    try:
577                        sub = self.mindm.add_subtopic_to_topic(topic, subtopic.text)
578                        self.set_topic_from_mindmap_topic(sub, subtopic, map_icons, done, done_global, level + 1)
579                    except Exception as e:
580                        print(f"Error(1) processing topic/subtopic {mindmap_topic.guid}/{subtopic.guid}: {e}")
581            else:
582                topic, topic_guid = self.mindm.set_topic_from_mindmap_topic(topic, mindmap_topic, map_icons)
583                self.update_done(topic_guid, mindmap_topic, level, done, done_global)
584
585                if mindmap_topic.subtopics and len(mindmap_topic.subtopics) > 0:
586                    # Sort subtopics alphabetically by text
587                    mindmap_topic.subtopics.sort(key=lambda sub: sub.text)
588
589                for subtopic in mindmap_topic.subtopics:
590                    try:
591                        if subtopic.guid in done:
592                            this_guid_as_parent_exists = self.check_parent_exists(topic_guid, subtopic.guid)
593                            if not this_guid_as_parent_exists:
594                                cloned_subtopic = self.clone_mindmap_topic(subtopic)
595                                sub = self.mindm.add_subtopic_to_topic(topic, cloned_subtopic.text)
596                                self.set_topic_from_mindmap_topic(sub, cloned_subtopic, map_icons, done, done_global, level + 1)
597                        else:
598                            sub = self.mindm.add_subtopic_to_topic(topic, subtopic.text)
599                            self.set_topic_from_mindmap_topic(sub, subtopic, map_icons, done, done_global, level + 1)
600                    except Exception as e:
601                        print(f"Error(2) processing topic/subtopic {mindmap_topic.guid}/{subtopic.guid}: {e}")
602            return mindmap_topic
603        except Exception as e:
604            print(f"Error in set_topic_from_mindmap_topic at level {level} with topic {mindmap_topic.guid}: {e}")
605
606    def check_parent_exists(self, topic_guid, this_guid, visited=None):
607        """
608        Recursively check if a parent-child relationship exists between topics.
609
610        Args:
611            topic_guid (str): The GUID of the topic to check.
612            this_guid (str): The GUID that might be a parent of the topic.
613            visited (set, optional): Set of visited GUIDs to avoid infinite recursion.
614
615        Returns:
616            bool: True if the parent-child relationship exists, False otherwise.
617        """
618        if visited is None:
619            visited = set()
620        if topic_guid in visited:
621            return False
622        visited.add(topic_guid)
623        
624        check = False
625        if topic_guid in self.parents:
626            parent_guid = self.parents[topic_guid]
627            if parent_guid == this_guid:
628                check = True
629            else:
630                check = self.check_parent_exists(parent_guid, this_guid, visited)
631        return check
632
633    def create_mindmap(self, verbose=False):
634        """
635        Create a MindManager mindmap document from the internal MindmapTopic structure.
636        This includes counting occurrences, extracting tags/icons, and setting up relationships and links.
637
638        Args:
639            verbose (bool): (Optional) Enable verbose output.
640        """
641        tags = []
642        map_icons = []
643        relationships = []
644        links = []
645
646        self.parents = {}
647        self.guid_counts = {}
648        self.count_parent_and_child_occurrences(self.mindmap, self.guid_counts)
649        self.get_parents_from_mindmap(self.mindmap, self.parents)
650
651        self.get_tags_from_mindmap(self.mindmap, tags)
652        self.get_map_icons_and_fix_refs_from_mindmap(self.mindmap, map_icons)
653        self.get_relationships_from_mindmap(self.mindmap, relationships)
654        self.get_topic_links_from_mindmap(self.mindmap, links)
655
656        self.mindm.add_document(0)
657        self.mindm.create_map_icons(map_icons)
658        self.mindm.create_tags(tags, DUPLICATED_TAG)
659        self.mindm.set_text_to_topic(self.mindm.get_central_topic(), self.mindmap.text)
660
661        topic = self.mindm.get_central_topic()
662
663        done_global = {}
664        self.set_topic_from_mindmap_topic(topic=topic, mindmap_topic=self.mindmap, map_icons=map_icons, done={}, done_global=done_global)
665
666        # Create relationships between topics
667        for reference in relationships:
668            object1_guids = done_global[reference.guid_1]
669            object2_guids = done_global[reference.guid_2]
670            for object1_guid in object1_guids:
671                for object2_guid in object2_guids:
672                    self.mindm.add_relationship(object1_guid, object2_guid, reference.label)
673
674        # Create topic links
675        for link in links:
676            object1_guids = done_global[link.guid_1]
677            object2_guids = done_global[link.guid_2]
678            for object1_guid in object1_guids:
679                for object2_guid in object2_guids:
680                    self.mindm.add_topic_link(object1_guid, object2_guid, link.label)
681
682    def create_mindmap_and_finalize(self):
683        """
684        Create the mindmap document and finalize it.
685        """
686        self.create_mindmap()
687        self.finalize()
688
689    def finalize(self):
690        """
691        Finalize the mindmap document by ensuring the maximum topic level is set, then calling MindManager's finalize.
692        """
693        if self.max_topic_level == 0:
694            self.max_topic_level = self.get_max_topic_level(self.mindmap)
695        self.mindm.finalize(self.max_topic_level)
696    
697    def set_background_image(self, image_path):
698        """
699        Set the background image for the MindManager document.
700
701        Args:
702            image_path (str): The file path to the background image.
703        """
704        self.mindm.set_document_background_image(image_path)
705    
706    def get_library_folder(self):
707        """
708        Get the library folder used by MindManager.
709
710        Returns:
711            The path to the library folder.
712        """
713        return self.mindm.get_library_folder()
714    
715    def get_grounding_information(self):
716        """
717        Extract grounding information from the mindmap, including the central topic and selected subtopics.
718
719        Returns:
720            tuple: (top_most_topic, subtopics) where top_most_topic is the central topic or a concatenated string
721                   of non-selected topics, and subtopics is a comma-separated string of selected subtopics.
722        """
723        central_topic_text = self.mindmap.text
724        subtopics = ""
725        if len(self.selected_topic_texts) == 0: 
726            top_most_topic = central_topic_text
727        else:
728            if self.central_topic_selected:
729                top_most_topic = central_topic_text
730                subtopics =  ",".join(self.selected_topic_texts)
731            else:
732                min_level = min(self.selected_topic_levels)
733                max_level = max(self.selected_topic_levels)
734                if (min_level == max_level):
735                    top_most_topic = central_topic_text
736                    subtopics =  ",".join(self.selected_topic_texts)
737                else:
738                    top_most_topic = ""
739                    for i in range(len(self.selected_topic_levels)):
740                        if self.selected_topic_levels[i] != max_level:
741                            top_most_topic += self.selected_topic_texts[i] + "/"
742                        else:
743                            subtopics += self.selected_topic_texts[i] + ","
744
745                    if top_most_topic.endswith("/"):
746                        top_most_topic = top_most_topic[:-1]
747                    if subtopics.endswith(","):
748                        subtopics = subtopics[:-1]        
749        return top_most_topic, subtopics