Cleanup: pep8
[blender-staging.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 = bpy.path.basename(path)
84         if type(name) == bytes:
85             name = name.decode("utf-8", "replace")
86         image = bpy.data.images.new(name, 128, 128)
87         # allow the path to be resolved later
88         image.filepath = path
89         image.source = 'FILE'
90         return image
91
92     def _image_load(path):
93         import bpy
94
95         if convert_callback:
96             path = convert_callback(path)
97
98         try:
99             image = bpy.data.images.load(path, check_existing)
100         except RuntimeError:
101             image = None
102
103         if verbose:
104             if image:
105                 print("    image loaded '%s'" % path)
106             else:
107                 print("    image load failed '%s'" % path)
108
109         # image path has been checked so the path could not be read for some
110         # reason, so be sure to return a placeholder
111         if place_holder and image is None:
112             image = _image_load_placeholder(path)
113
114         if image:
115             if force_reload:
116                 image.reload()
117             if relpath is not None:
118                 # make relative
119                 from bpy.path import relpath as relpath_fn
120                 # can't always find the relative path
121                 # (between drive letters on windows)
122                 try:
123                     filepath_rel = relpath_fn(path, start=relpath)
124                 except ValueError:
125                     filepath_rel = None
126
127                 if filepath_rel is not None:
128                     image.filepath_raw = filepath_rel
129
130         return image
131
132     def _recursive_search(paths, filename_check):
133         for path in paths:
134             for dirpath, dirnames, filenames in os.walk(path):
135
136                 # skip '.svn'
137                 if dirpath[0] in {".", b'.'}:
138                     continue
139
140                 for filename in filenames:
141                     if filename_check(filename):
142                         yield os.path.join(dirpath, filename)
143
144     # -------------------------------------------------------------------------
145
146     if verbose:
147         print("load_image('%s', '%s', ...)" % (imagepath, dirname))
148
149     if os.path.exists(imagepath):
150         return _image_load(imagepath)
151
152     variants = [imagepath]
153
154     if dirname:
155         variants += [os.path.join(dirname, imagepath),
156                      os.path.join(dirname, bpy.path.basename(imagepath)),
157                      ]
158
159     for filepath_test in variants:
160         if ncase_cmp:
161             ncase_variants = (filepath_test,
162                               bpy.path.resolve_ncase(filepath_test),
163                               )
164         else:
165             ncase_variants = (filepath_test, )
166
167         for nfilepath in ncase_variants:
168             if os.path.exists(nfilepath):
169                 return _image_load(nfilepath)
170
171     if recursive:
172         search_paths = []
173
174         for dirpath_test in (os.path.dirname(imagepath), dirname):
175             if os.path.exists(dirpath_test):
176                 search_paths.append(dirpath_test)
177         search_paths[:] = bpy.path.reduce_dirs(search_paths)
178
179         imagepath_base = bpy.path.basename(imagepath)
180         if ncase_cmp:
181             imagepath_base = imagepath_base.lower()
182
183             def image_filter(fn):
184                 return (imagepath_base == fn.lower())
185         else:
186             def image_filter(fn):
187                 return (imagepath_base == fn)
188
189         nfilepath = next(_recursive_search(search_paths, image_filter), None)
190         if nfilepath is not None:
191             return _image_load(nfilepath)
192
193     # None of the paths exist so return placeholder
194     if place_holder:
195         return _image_load_placeholder(imagepath)
196
197     # TODO comprehensiveImageLoad also searched in bpy.config.textureDir
198     return None