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:`bpy.types.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