Fix image_utils.py's load_image() helper.
[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                relpath=None,
35                check_existing=False,
36                force_reload=False,
37                ):
38     """
39     Return an image from the file path with options to search multiple paths
40     and return a placeholder if its not found.
41
42     :arg filepath: The image filename
43        If a path precedes it, this will be searched as well.
44     :type filepath: string
45     :arg dirname: is the directory where the image may be located - any file at
46        the end will be ignored.
47     :type dirname: string
48     :arg place_holder: if True a new place holder image will be created.
49        this is useful so later you can relink the image to its original data.
50     :type place_holder: bool
51     :arg recursive: If True, directories will be recursively searched.
52        Be careful with this if you have files in your root directory because
53        it may take a long time.
54     :type recursive: bool
55     :arg ncase_cmp: on non windows systems, find the correct case for the file.
56     :type ncase_cmp: bool
57     :arg convert_callback: a function that takes an existing path and returns
58        a new one. Use this when loading image formats blender may not support,
59        the CONVERT_CALLBACK can take the path for a GIF (for example),
60        convert it to a PNG and return the PNG's path.
61        For formats blender can read, simply return the path that is given.
62     :type convert_callback: function
63     :arg relpath: If not None, make the file relative to this path.
64     :type relpath: None or string
65     :arg check_existing: If true,
66        returns already loaded image datablock if possible
67        (based on file path).
68     :type check_existing: bool
69     :arg force_reload: If true,
70        force reloading of image (only useful when `check_existing`
71        is also enabled).
72     :type force_reload: bool
73     :return: an image or None
74     :rtype: :class:`bpy.types.Image`
75     """
76     import os
77     import bpy
78
79     # -------------------------------------------------------------------------
80     # Utility Functions
81
82     def _image_load_placeholder(path):
83         name = path
84         if type(path) is str:
85             name = name.encode("utf-8", "replace")
86         name = name.decode("utf-8", "replace")
87         name = os.path.basename(name)
88
89         image = bpy.data.images.new(name, 128, 128)
90         # allow the path to be resolved later
91         image.filepath = path
92         image.source = 'FILE'
93         return image
94
95     def _image_load(path):
96         import bpy
97
98         if convert_callback:
99             path = convert_callback(path)
100
101         # Ensure we're not relying on the 'CWD' to resolve the path.
102         if not os.path.isabs(path):
103             path = os.path.abspath(path)
104
105         try:
106             image = bpy.data.images.load(path, check_existing=check_existing)
107         except RuntimeError:
108             image = None
109
110         if verbose:
111             if image:
112                 print("    image loaded '%s'" % path)
113             else:
114                 print("    image load failed '%s'" % path)
115
116         # image path has been checked so the path could not be read for some
117         # reason, so be sure to return a placeholder
118         if place_holder and image is None:
119             image = _image_load_placeholder(path)
120
121         if image:
122             if force_reload:
123                 image.reload()
124             if relpath is not None:
125                 # make relative
126                 from bpy.path import relpath as relpath_fn
127                 # can't always find the relative path
128                 # (between drive letters on windows)
129                 try:
130                     filepath_rel = relpath_fn(path, start=relpath)
131                 except ValueError:
132                     filepath_rel = None
133
134                 if filepath_rel is not None:
135                     image.filepath_raw = filepath_rel
136
137         return image
138
139     def _recursive_search(paths, filename_check):
140         for path in paths:
141             for dirpath, dirnames, filenames in os.walk(path):
142
143                 # skip '.svn'
144                 if dirpath[0] in {".", b'.'}:
145                     continue
146
147                 for filename in filenames:
148                     if filename_check(filename):
149                         yield os.path.join(dirpath, filename)
150
151     # -------------------------------------------------------------------------
152
153     imagepath = bpy.path.native_pathsep(imagepath)
154
155     if verbose:
156         print("load_image('%s', '%s', ...)" % (imagepath, dirname))
157
158     if os.path.exists(imagepath):
159         return _image_load(imagepath)
160
161     variants = [imagepath]
162
163     if dirname:
164         variants += [os.path.join(dirname, imagepath),
165                      os.path.join(dirname, bpy.path.basename(imagepath)),
166                      ]
167
168     for filepath_test in variants:
169         if ncase_cmp:
170             ncase_variants = (filepath_test,
171                               bpy.path.resolve_ncase(filepath_test),
172                               )
173         else:
174             ncase_variants = (filepath_test, )
175
176         for nfilepath in ncase_variants:
177             if os.path.exists(nfilepath):
178                 return _image_load(nfilepath)
179
180     if recursive:
181         search_paths = []
182
183         for dirpath_test in (os.path.dirname(imagepath), dirname):
184             if os.path.exists(dirpath_test):
185                 search_paths.append(dirpath_test)
186         search_paths[:] = bpy.path.reduce_dirs(search_paths)
187
188         imagepath_base = bpy.path.basename(imagepath)
189         if ncase_cmp:
190             imagepath_base = imagepath_base.lower()
191
192             def image_filter(fn):
193                 return (imagepath_base == fn.lower())
194         else:
195             def image_filter(fn):
196                 return (imagepath_base == fn)
197
198         nfilepath = next(_recursive_search(search_paths, image_filter), None)
199         if nfilepath is not None:
200             return _image_load(nfilepath)
201
202     # None of the paths exist so return placeholder
203     if place_holder:
204         return _image_load_placeholder(imagepath)
205
206     # TODO comprehensiveImageLoad also searched in bpy.config.textureDir
207     return None