65ccc3f8dc3cf46ff04a8e16ac2cfdee2edabe39
[blender-staging.git] / release / scripts / modules / bpy_extras / io_utils.py
1 # ##### BEGIN GPL LICENSE BLOCK #####
2 #
3 #  This program is free software; you can redistribute it and/or
4 #  modify it under the terms of the GNU General Public License
5 #  as published by the Free Software Foundation; either version 2
6 #  of the License, or (at your option) any later version.
7 #
8 #  This program is distributed in the hope that it will be useful,
9 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
10 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11 #  GNU General Public License for more details.
12 #
13 #  You should have received a copy of the GNU General Public License
14 #  along with this program; if not, write to the Free Software Foundation,
15 #  Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 #
17 # ##### END GPL LICENSE BLOCK #####
18
19 # <pep8-80 compliant>
20
21 __all__ = (
22     "ExportHelper",
23     "ImportHelper",
24     "orientation_helper_factory",
25     "axis_conversion",
26     "axis_conversion_ensure",
27     "create_derived_objects",
28     "free_derived_objects",
29     "unpack_list",
30     "unpack_face_list",
31     "path_reference",
32     "path_reference_copy",
33     "path_reference_mode",
34     "unique_name"
35     )
36
37 import bpy
38 from bpy.props import (
39         StringProperty,
40         BoolProperty,
41         EnumProperty,
42         )
43
44
45 def _check_axis_conversion(op):
46     if hasattr(op, "axis_forward") and hasattr(op, "axis_up"):
47         return axis_conversion_ensure(op,
48                                       "axis_forward",
49                                       "axis_up",
50                                       )
51     return False
52
53
54 class ExportHelper:
55     filepath = StringProperty(
56             name="File Path",
57             description="Filepath used for exporting the file",
58             maxlen=1024,
59             subtype='FILE_PATH',
60             )
61     check_existing = BoolProperty(
62             name="Check Existing",
63             description="Check and warn on overwriting existing files",
64             default=True,
65             options={'HIDDEN'},
66             )
67
68     # needed for mix-ins
69     order = [
70         "filepath",
71         "check_existing",
72         ]
73
74     # subclasses can override with decorator
75     # True == use ext, False == no ext, None == do nothing.
76     check_extension = True
77
78     def invoke(self, context, event):
79         import os
80         if not self.filepath:
81             blend_filepath = context.blend_data.filepath
82             if not blend_filepath:
83                 blend_filepath = "untitled"
84             else:
85                 blend_filepath = os.path.splitext(blend_filepath)[0]
86
87             self.filepath = blend_filepath + self.filename_ext
88
89         context.window_manager.fileselect_add(self)
90         return {'RUNNING_MODAL'}
91
92     def check(self, context):
93         import os
94         change_ext = False
95         change_axis = _check_axis_conversion(self)
96
97         check_extension = self.check_extension
98
99         if check_extension is not None:
100             filepath = self.filepath
101             if os.path.basename(filepath):
102                 filepath = bpy.path.ensure_ext(filepath,
103                                                self.filename_ext
104                                                if check_extension
105                                                else "")
106
107                 if filepath != self.filepath:
108                     self.filepath = filepath
109                     change_ext = True
110
111         return (change_ext or change_axis)
112
113
114 class ImportHelper:
115     filepath = StringProperty(
116             name="File Path",
117             description="Filepath used for importing the file",
118             maxlen=1024,
119             subtype='FILE_PATH',
120             )
121
122     # needed for mix-ins
123     order = [
124         "filepath",
125         ]
126
127     def invoke(self, context, event):
128         context.window_manager.fileselect_add(self)
129         return {'RUNNING_MODAL'}
130
131     def check(self, context):
132         return _check_axis_conversion(self)
133
134
135 def orientation_helper_factory(name, axis_forward='Y', axis_up='Z'):
136     members = {}
137
138     def _update_axis_forward(self, context):
139         if self.axis_forward[-1] == self.axis_up[-1]:
140             self.axis_up = self.axis_up[0:-1] + 'XYZ'[('XYZ'.index(self.axis_up[-1]) + 1) % 3]
141
142     members['axis_forward'] = EnumProperty(
143             name="Forward",
144             items=(('X', "X Forward", ""),
145                    ('Y', "Y Forward", ""),
146                    ('Z', "Z Forward", ""),
147                    ('-X', "-X Forward", ""),
148                    ('-Y', "-Y Forward", ""),
149                    ('-Z', "-Z Forward", ""),
150                    ),
151             default=axis_forward,
152             update=_update_axis_forward,
153             )
154
155     def _update_axis_up(self, context):
156         if self.axis_up[-1] == self.axis_forward[-1]:
157             self.axis_forward = self.axis_forward[0:-1] + 'XYZ'[('XYZ'.index(self.axis_forward[-1]) + 1) % 3]
158
159     members['axis_up'] = EnumProperty(
160             name="Up",
161             items=(('X', "X Up", ""),
162                    ('Y', "Y Up", ""),
163                    ('Z', "Z Up", ""),
164                    ('-X', "-X Up", ""),
165                    ('-Y', "-Y Up", ""),
166                    ('-Z', "-Z Up", ""),
167                    ),
168             default=axis_up,
169             update=_update_axis_up,
170             )
171
172     members["order"] = [
173         "axis_forward",
174         "axis_up",
175         ]
176
177     return type(name, (object,), members)
178
179
180 # Axis conversion function, not pretty LUT
181 # use lookup table to convert between any axis
182 _axis_convert_matrix = (
183     ((-1.0, 0.0, 0.0), (0.0, -1.0, 0.0), (0.0, 0.0, 1.0)),
184     ((-1.0, 0.0, 0.0), (0.0, 0.0, -1.0), (0.0, -1.0, 0.0)),
185     ((-1.0, 0.0, 0.0), (0.0, 0.0, 1.0), (0.0, 1.0, 0.0)),
186     ((-1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, -1.0)),
187     ((0.0, -1.0, 0.0), (-1.0, 0.0, 0.0), (0.0, 0.0, -1.0)),
188     ((0.0, 0.0, 1.0), (-1.0, 0.0, 0.0), (0.0, -1.0, 0.0)),
189     ((0.0, 0.0, -1.0), (-1.0, 0.0, 0.0), (0.0, 1.0, 0.0)),
190     ((0.0, 1.0, 0.0), (-1.0, 0.0, 0.0), (0.0, 0.0, 1.0)),
191     ((0.0, -1.0, 0.0), (0.0, 0.0, 1.0), (-1.0, 0.0, 0.0)),
192     ((0.0, 0.0, -1.0), (0.0, -1.0, 0.0), (-1.0, 0.0, 0.0)),
193     ((0.0, 0.0, 1.0), (0.0, 1.0, 0.0), (-1.0, 0.0, 0.0)),
194     ((0.0, 1.0, 0.0), (0.0, 0.0, -1.0), (-1.0, 0.0, 0.0)),
195     ((0.0, -1.0, 0.0), (0.0, 0.0, -1.0), (1.0, 0.0, 0.0)),
196     ((0.0, 0.0, 1.0), (0.0, -1.0, 0.0), (1.0, 0.0, 0.0)),
197     ((0.0, 0.0, -1.0), (0.0, 1.0, 0.0), (1.0, 0.0, 0.0)),
198     ((0.0, 1.0, 0.0), (0.0, 0.0, 1.0), (1.0, 0.0, 0.0)),
199     ((0.0, -1.0, 0.0), (1.0, 0.0, 0.0), (0.0, 0.0, 1.0)),
200     ((0.0, 0.0, -1.0), (1.0, 0.0, 0.0), (0.0, -1.0, 0.0)),
201     ((0.0, 0.0, 1.0), (1.0, 0.0, 0.0), (0.0, 1.0, 0.0)),
202     ((0.0, 1.0, 0.0), (1.0, 0.0, 0.0), (0.0, 0.0, -1.0)),
203     ((1.0, 0.0, 0.0), (0.0, -1.0, 0.0), (0.0, 0.0, -1.0)),
204     ((1.0, 0.0, 0.0), (0.0, 0.0, 1.0), (0.0, -1.0, 0.0)),
205     ((1.0, 0.0, 0.0), (0.0, 0.0, -1.0), (0.0, 1.0, 0.0)),
206     )
207
208 # store args as a single int
209 # (X Y Z -X -Y -Z) --> (0, 1, 2, 3, 4, 5)
210 # each value is ((src_forward, src_up), (dst_forward, dst_up))
211 # where all 4 values are or'd into a single value...
212 #    (i1<<0 | i1<<3 | i1<<6 | i1<<9)
213 _axis_convert_lut = (
214     {0x8C8, 0x4D0, 0x2E0, 0xAE8, 0x701, 0x511, 0x119, 0xB29, 0x682, 0x88A,
215      0x09A, 0x2A2, 0x80B, 0x413, 0x223, 0xA2B, 0x644, 0x454, 0x05C, 0xA6C,
216      0x745, 0x94D, 0x15D, 0x365},
217     {0xAC8, 0x8D0, 0x4E0, 0x2E8, 0x741, 0x951, 0x159, 0x369, 0x702, 0xB0A,
218      0x11A, 0x522, 0xA0B, 0x813, 0x423, 0x22B, 0x684, 0x894, 0x09C, 0x2AC,
219      0x645, 0xA4D, 0x05D, 0x465},
220     {0x4C8, 0x2D0, 0xAE0, 0x8E8, 0x681, 0x291, 0x099, 0x8A9, 0x642, 0x44A,
221      0x05A, 0xA62, 0x40B, 0x213, 0xA23, 0x82B, 0x744, 0x354, 0x15C, 0x96C,
222      0x705, 0x50D, 0x11D, 0xB25},
223     {0x2C8, 0xAD0, 0x8E0, 0x4E8, 0x641, 0xA51, 0x059, 0x469, 0x742, 0x34A,
224      0x15A, 0x962, 0x20B, 0xA13, 0x823, 0x42B, 0x704, 0xB14, 0x11C, 0x52C,
225      0x685, 0x28D, 0x09D, 0x8A5},
226     {0x708, 0xB10, 0x120, 0x528, 0x8C1, 0xAD1, 0x2D9, 0x4E9, 0x942, 0x74A,
227      0x35A, 0x162, 0x64B, 0xA53, 0x063, 0x46B, 0x804, 0xA14, 0x21C, 0x42C,
228      0x885, 0x68D, 0x29D, 0x0A5},
229     {0xB08, 0x110, 0x520, 0x728, 0x941, 0x151, 0x359, 0x769, 0x802, 0xA0A,
230      0x21A, 0x422, 0xA4B, 0x053, 0x463, 0x66B, 0x884, 0x094, 0x29C, 0x6AC,
231      0x8C5, 0xACD, 0x2DD, 0x4E5},
232     {0x508, 0x710, 0xB20, 0x128, 0x881, 0x691, 0x299, 0x0A9, 0x8C2, 0x4CA,
233      0x2DA, 0xAE2, 0x44B, 0x653, 0xA63, 0x06B, 0x944, 0x754, 0x35C, 0x16C,
234      0x805, 0x40D, 0x21D, 0xA25},
235     {0x108, 0x510, 0x720, 0xB28, 0x801, 0x411, 0x219, 0xA29, 0x882, 0x08A,
236      0x29A, 0x6A2, 0x04B, 0x453, 0x663, 0xA6B, 0x8C4, 0x4D4, 0x2DC, 0xAEC,
237      0x945, 0x14D, 0x35D, 0x765},
238     {0x748, 0x350, 0x160, 0x968, 0xAC1, 0x2D1, 0x4D9, 0x8E9, 0xA42, 0x64A,
239      0x45A, 0x062, 0x68B, 0x293, 0x0A3, 0x8AB, 0xA04, 0x214, 0x41C, 0x82C,
240      0xB05, 0x70D, 0x51D, 0x125},
241     {0x948, 0x750, 0x360, 0x168, 0xB01, 0x711, 0x519, 0x129, 0xAC2, 0x8CA,
242      0x4DA, 0x2E2, 0x88B, 0x693, 0x2A3, 0x0AB, 0xA44, 0x654, 0x45C, 0x06C,
243      0xA05, 0x80D, 0x41D, 0x225},
244     {0x348, 0x150, 0x960, 0x768, 0xA41, 0x051, 0x459, 0x669, 0xA02, 0x20A,
245      0x41A, 0x822, 0x28B, 0x093, 0x8A3, 0x6AB, 0xB04, 0x114, 0x51C, 0x72C,
246      0xAC5, 0x2CD, 0x4DD, 0x8E5},
247     {0x148, 0x950, 0x760, 0x368, 0xA01, 0x811, 0x419, 0x229, 0xB02, 0x10A,
248      0x51A, 0x722, 0x08B, 0x893, 0x6A3, 0x2AB, 0xAC4, 0x8D4, 0x4DC, 0x2EC,
249      0xA45, 0x04D, 0x45D, 0x665},
250     {0x688, 0x890, 0x0A0, 0x2A8, 0x4C1, 0x8D1, 0xAD9, 0x2E9, 0x502, 0x70A,
251      0xB1A, 0x122, 0x74B, 0x953, 0x163, 0x36B, 0x404, 0x814, 0xA1C, 0x22C,
252      0x445, 0x64D, 0xA5D, 0x065},
253     {0x888, 0x090, 0x2A0, 0x6A8, 0x501, 0x111, 0xB19, 0x729, 0x402, 0x80A,
254      0xA1A, 0x222, 0x94B, 0x153, 0x363, 0x76B, 0x444, 0x054, 0xA5C, 0x66C,
255      0x4C5, 0x8CD, 0xADD, 0x2E5},
256     {0x288, 0x690, 0x8A0, 0x0A8, 0x441, 0x651, 0xA59, 0x069, 0x4C2, 0x2CA,
257      0xADA, 0x8E2, 0x34B, 0x753, 0x963, 0x16B, 0x504, 0x714, 0xB1C, 0x12C,
258      0x405, 0x20D, 0xA1D, 0x825},
259     {0x088, 0x290, 0x6A0, 0x8A8, 0x401, 0x211, 0xA19, 0x829, 0x442, 0x04A,
260      0xA5A, 0x662, 0x14B, 0x353, 0x763, 0x96B, 0x4C4, 0x2D4, 0xADC, 0x8EC,
261      0x505, 0x10D, 0xB1D, 0x725},
262     {0x648, 0x450, 0x060, 0xA68, 0x2C1, 0x4D1, 0x8D9, 0xAE9, 0x282, 0x68A,
263      0x89A, 0x0A2, 0x70B, 0x513, 0x123, 0xB2B, 0x204, 0x414, 0x81C, 0xA2C,
264      0x345, 0x74D, 0x95D, 0x165},
265     {0xA48, 0x650, 0x460, 0x068, 0x341, 0x751, 0x959, 0x169, 0x2C2, 0xACA,
266      0x8DA, 0x4E2, 0xB0B, 0x713, 0x523, 0x12B, 0x284, 0x694, 0x89C, 0x0AC,
267      0x205, 0xA0D, 0x81D, 0x425},
268     {0x448, 0x050, 0xA60, 0x668, 0x281, 0x091, 0x899, 0x6A9, 0x202, 0x40A,
269      0x81A, 0xA22, 0x50B, 0x113, 0xB23, 0x72B, 0x344, 0x154, 0x95C, 0x76C,
270      0x2C5, 0x4CD, 0x8DD, 0xAE5},
271     {0x048, 0xA50, 0x660, 0x468, 0x201, 0xA11, 0x819, 0x429, 0x342, 0x14A,
272      0x95A, 0x762, 0x10B, 0xB13, 0x723, 0x52B, 0x2C4, 0xAD4, 0x8DC, 0x4EC,
273      0x285, 0x08D, 0x89D, 0x6A5},
274     {0x808, 0xA10, 0x220, 0x428, 0x101, 0xB11, 0x719, 0x529, 0x142, 0x94A,
275      0x75A, 0x362, 0x8CB, 0xAD3, 0x2E3, 0x4EB, 0x044, 0xA54, 0x65C, 0x46C,
276      0x085, 0x88D, 0x69D, 0x2A5},
277     {0xA08, 0x210, 0x420, 0x828, 0x141, 0x351, 0x759, 0x969, 0x042, 0xA4A,
278      0x65A, 0x462, 0xACB, 0x2D3, 0x4E3, 0x8EB, 0x084, 0x294, 0x69C, 0x8AC,
279      0x105, 0xB0D, 0x71D, 0x525},
280     {0x408, 0x810, 0xA20, 0x228, 0x081, 0x891, 0x699, 0x2A9, 0x102, 0x50A,
281      0x71A, 0xB22, 0x4CB, 0x8D3, 0xAE3, 0x2EB, 0x144, 0x954, 0x75C, 0x36C,
282      0x045, 0x44D, 0x65D, 0xA65},
283     )
284
285 _axis_convert_num = {'X': 0, 'Y': 1, 'Z': 2, '-X': 3, '-Y': 4, '-Z': 5}
286
287
288 def axis_conversion(from_forward='Y', from_up='Z', to_forward='Y', to_up='Z'):
289     """
290     Each argument us an axis in ['X', 'Y', 'Z', '-X', '-Y', '-Z']
291     where the first 2 are a source and the second 2 are the target.
292     """
293     from mathutils import Matrix
294     from functools import reduce
295
296     if from_forward == to_forward and from_up == to_up:
297         return Matrix().to_3x3()
298
299     if from_forward[-1] == from_up[-1] or to_forward[-1] == to_up[-1]:
300         raise Exception("Invalid axis arguments passed, "
301                         "can't use up/forward on the same axis")
302
303     value = reduce(int.__or__, (_axis_convert_num[a] << (i * 3)
304                    for i, a in enumerate((from_forward,
305                                           from_up,
306                                           to_forward,
307                                           to_up,
308                                           ))))
309
310     for i, axis_lut in enumerate(_axis_convert_lut):
311         if value in axis_lut:
312             return Matrix(_axis_convert_matrix[i])
313     assert(0)
314
315
316 def axis_conversion_ensure(operator, forward_attr, up_attr):
317     """
318     Function to ensure an operator has valid axis conversion settings, intended
319     to be used from :class:`bpy.types.Operator.check`.
320
321     :arg operator: the operator to access axis attributes from.
322     :type operator: :class:`bpy.types.Operator`
323     :arg forward_attr: attribute storing the forward axis
324     :type forward_attr: string
325     :arg up_attr: attribute storing the up axis
326     :type up_attr: string
327     :return: True if the value was modified.
328     :rtype: boolean
329     """
330     def validate(axis_forward, axis_up):
331         if axis_forward[-1] == axis_up[-1]:
332             axis_up = axis_up[0:-1] + 'XYZ'[('XYZ'.index(axis_up[-1]) + 1) % 3]
333
334         return axis_forward, axis_up
335
336     axis = getattr(operator, forward_attr), getattr(operator, up_attr)
337     axis_new = validate(*axis)
338
339     if axis != axis_new:
340         setattr(operator, forward_attr, axis_new[0])
341         setattr(operator, up_attr, axis_new[1])
342
343         return True
344     else:
345         return False
346
347
348 # return a tuple (free, object list), free is True if memory should be freed
349 # later with free_derived_objects()
350 def create_derived_objects(scene, ob):
351     if ob.parent and ob.parent.dupli_type in {'VERTS', 'FACES'}:
352         return False, None
353
354     if ob.dupli_type != 'NONE':
355         ob.dupli_list_create(scene)
356         return True, [(dob.object, dob.matrix) for dob in ob.dupli_list]
357     else:
358         return False, [(ob, ob.matrix_world)]
359
360
361 def free_derived_objects(ob):
362     ob.dupli_list_clear()
363
364
365 def unpack_list(list_of_tuples):
366     flat_list = []
367     flat_list_extend = flat_list.extend  # a tiny bit faster
368     for t in list_of_tuples:
369         flat_list_extend(t)
370     return flat_list
371
372
373 # same as above except that it adds 0 for triangle faces
374 def unpack_face_list(list_of_tuples):
375     # allocate the entire list
376     flat_ls = [0] * (len(list_of_tuples) * 4)
377     i = 0
378
379     for t in list_of_tuples:
380         if len(t) == 3:
381             if t[2] == 0:
382                 t = t[1], t[2], t[0]
383         else:  # assume quad
384             if t[3] == 0 or t[2] == 0:
385                 t = t[2], t[3], t[0], t[1]
386
387         flat_ls[i:i + len(t)] = t
388         i += 4
389     return flat_ls
390
391
392 path_reference_mode = EnumProperty(
393         name="Path Mode",
394         description="Method used to reference paths",
395         items=(('AUTO', "Auto", "Use Relative paths with subdirectories only"),
396                ('ABSOLUTE', "Absolute", "Always write absolute paths"),
397                ('RELATIVE', "Relative", "Always write relative paths "
398                                         "(where possible)"),
399                ('MATCH', "Match", "Match Absolute/Relative "
400                                   "setting with input path"),
401                ('STRIP', "Strip Path", "Filename only"),
402                ('COPY', "Copy", "Copy the file to the destination path "
403                                 "(or subdirectory)"),
404                ),
405         default='AUTO',
406         )
407
408
409 def path_reference(filepath,
410                    base_src,
411                    base_dst,
412                    mode='AUTO',
413                    copy_subdir="",
414                    copy_set=None,
415                    library=None,
416                    ):
417     """
418     Return a filepath relative to a destination directory, for use with
419     exporters.
420
421     :arg filepath: the file path to return,
422        supporting blenders relative '//' prefix.
423     :type filepath: string
424     :arg base_src: the directory the *filepath* is relative too
425        (normally the blend file).
426     :type base_src: string
427     :arg base_dst: the directory the *filepath* will be referenced from
428        (normally the export path).
429     :type base_dst: string
430     :arg mode: the method used get the path in
431        ['AUTO', 'ABSOLUTE', 'RELATIVE', 'MATCH', 'STRIP', 'COPY']
432     :type mode: string
433     :arg copy_subdir: the subdirectory of *base_dst* to use when mode='COPY'.
434     :type copy_subdir: string
435     :arg copy_set: collect from/to pairs when mode='COPY',
436        pass to *path_reference_copy* when exporting is done.
437     :type copy_set: set
438     :arg library: The library this path is relative to.
439     :type library: :class:`bpy.types.Library` or None
440     :return: the new filepath.
441     :rtype: string
442     """
443     import os
444     is_relative = filepath.startswith("//")
445     filepath_abs = bpy.path.abspath(filepath, base_src, library)
446     filepath_abs = os.path.normpath(filepath_abs)
447
448     if mode in {'ABSOLUTE', 'RELATIVE', 'STRIP'}:
449         pass
450     elif mode == 'MATCH':
451         mode = 'RELATIVE' if is_relative else 'ABSOLUTE'
452     elif mode == 'AUTO':
453         mode = ('RELATIVE'
454                 if bpy.path.is_subdir(filepath_abs, base_dst)
455                 else 'ABSOLUTE')
456     elif mode == 'COPY':
457         subdir_abs = os.path.normpath(base_dst)
458         if copy_subdir:
459             subdir_abs = os.path.join(subdir_abs, copy_subdir)
460
461         filepath_cpy = os.path.join(subdir_abs, os.path.basename(filepath))
462
463         copy_set.add((filepath_abs, filepath_cpy))
464
465         filepath_abs = filepath_cpy
466         mode = 'RELATIVE'
467     else:
468         raise Exception("invalid mode given %r" % mode)
469
470     if mode == 'ABSOLUTE':
471         return filepath_abs
472     elif mode == 'RELATIVE':
473         # can't always find the relative path
474         # (between drive letters on windows)
475         try:
476             return os.path.relpath(filepath_abs, base_dst)
477         except ValueError:
478             return filepath_abs
479     elif mode == 'STRIP':
480         return os.path.basename(filepath_abs)
481
482
483 def path_reference_copy(copy_set, report=print):
484     """
485     Execute copying files of path_reference
486
487     :arg copy_set: set of (from, to) pairs to copy.
488     :type copy_set: set
489     :arg report: function used for reporting warnings, takes a string argument.
490     :type report: function
491     """
492     if not copy_set:
493         return
494
495     import os
496     import shutil
497
498     for file_src, file_dst in copy_set:
499         if not os.path.exists(file_src):
500             report("missing %r, not copying" % file_src)
501         elif os.path.exists(file_dst) and os.path.samefile(file_src, file_dst):
502             pass
503         else:
504             dir_to = os.path.dirname(file_dst)
505
506             try:
507                 os.makedirs(dir_to, exist_ok=True)
508             except:
509                 import traceback
510                 traceback.print_exc()
511
512             try:
513                 shutil.copy(file_src, file_dst)
514             except:
515                 import traceback
516                 traceback.print_exc()
517
518
519 def unique_name(key, name, name_dict, name_max=-1, clean_func=None, sep="."):
520     """
521     Helper function for storing unique names which may have special characters
522     stripped and restricted to a maximum length.
523
524     :arg key: unique item this name belongs to, name_dict[key] will be reused
525        when available.
526        This can be the object, mesh, material, etc instance its self.
527     :type key: any hashable object associated with the *name*.
528     :arg name: The name used to create a unique value in *name_dict*.
529     :type name: string
530     :arg name_dict: This is used to cache namespace to ensure no collisions
531        occur, this should be an empty dict initially and only modified by this
532        function.
533     :type name_dict: dict
534     :arg clean_func: Function to call on *name* before creating a unique value.
535     :type clean_func: function
536     :arg sep: Separator to use when between the name and a number when a
537        duplicate name is found.
538     :type sep: string
539     """
540     name_new = name_dict.get(key)
541     if name_new is None:
542         count = 1
543         name_dict_values = name_dict.values()
544         name_new = name_new_orig = (name if clean_func is None
545                                     else clean_func(name))
546
547         if name_max == -1:
548             while name_new in name_dict_values:
549                 name_new = "%s%s%03d" % (name_new_orig, sep, count)
550                 count += 1
551         else:
552             name_new = name_new[:name_max]
553             while name_new in name_dict_values:
554                 count_str = "%03d" % count
555                 name_new = "%.*s%s%s" % (name_max - (len(count_str) + 1),
556                                          name_new_orig,
557                                          sep,
558                                          count_str,
559                                          )
560                 count += 1
561
562         name_dict[key] = name_new
563
564     return name_new