eab75c3bd16a36503f7aaf88b09612d735060676
[blender.git] / release / scripts / modules / bpy_extras / image_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     "load_image",
23     )
24
25
26 # limited replacement for BPyImage.comprehensiveImageLoad
27 def load_image(imagepath,
28                dirname="",
29                place_holder=False,
30                recursive=False,
31                ncase_cmp=True,
32                convert_callback=None,
33                verbose=False,
34                ):
35     """
36     Return an image from the file path with options to search multiple paths
37     and return a placeholder if its not found.
38
39     :arg filepath: The image filename
40        If a path precedes it, this will be searched as well.
41     :type filepath: string
42     :arg dirname: is the directory where the image may be located - any file at
43        the end will be ignored.
44     :type dirname: string
45     :arg place_holder: if True a new place holder image will be created.
46        this is usefull so later you can relink the image to its original data.
47     :type place_holder: bool
48     :arg recursive: If True, directories will be recursivly searched.
49        Be carefull with this if you have files in your root directory because
50        it may take a long time.
51     :type recursive: bool
52     :arg ncase_cmp: on non windows systems, find the correct case for the file.
53     :type ncase_cmp: bool
54     :arg convert_callback: a function that takes an existing path and returns
55        a new one. Use this when loading image formats blender may not support,
56        the CONVERT_CALLBACK can take the path for a GIF (for example),
57        convert it to a PNG and return the PNG's path.
58        For formats blender can read, simply return the path that is given.
59     :type convert_callback: function
60     :return: an image or None
61     :rtype: :class:`Image`
62     """
63     import os
64     import bpy
65
66     # TODO: recursive
67
68     def _image_load(path):
69         import bpy
70
71         if convert_callback:
72             path = convert_callback(path)
73
74         image = bpy.data.images.load(path)
75
76         if verbose:
77             print("    image loaded '%s'" % path)
78
79         return image
80
81     if verbose:
82         print("load_image('%s', '%s', ...)" % (imagepath, dirname))
83
84     if os.path.exists(imagepath):
85         return _image_load(imagepath)
86
87     variants = [imagepath]
88
89     if dirname:
90         variants += [os.path.join(dirname, imagepath),
91                      os.path.join(dirname, bpy.path.basename(imagepath)),
92                      ]
93
94     for filepath_test in variants:
95         if ncase_cmp:
96             ncase_variants = (filepath_test,
97                               bpy.path.resolve_ncase(filepath_test),
98                               )
99         else:
100             ncase_variants = (filepath_test, )
101
102         for nfilepath in ncase_variants:
103             if os.path.exists(nfilepath):
104                 return _image_load(nfilepath)
105
106     if place_holder:
107         image = bpy.data.images.new(bpy.path.basename(imagepath), 128, 128)
108         # allow the path to be resolved later
109         image.filepath = imagepath
110         return image
111
112     # TODO comprehensiveImageLoad also searched in bpy.config.textureDir
113     return None