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