1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
package Torello.HTML.Tools.Images;

import java.util.regex.*;
import java.io.*;

import java.awt.image.BufferedImage;
import javax.imageio.ImageIO;
import java.util.Base64;
import java.net.URL;

import Torello.Java.Additional.Ret2;

/**
 * <CODE>IF (Image Format) - Documentation.</CODE><BR /><BR />
 * <EMBED CLASS="external-html" DATA-FILE-ID="IF">
 * @see ImageScrape
 * @see ImageScraper
 */
public enum IF
{
    /**
     * Used to indicate a picture using the common {@code '.jpg'} image format.
     * According to a <B>Yahoo! Search</B> link:
     * 
     * <BR /><BR /><CODE> The JPEG file extension is used interchangeably
     * with JPG. JPEG stands for Joint Photographic Experts Group who created the standard. 
     * JPG files have 2 sub-formats, JPG/ Exif (often used in digital cameras and photographic 
     * equipment), and JPG/ JFIF (often used on the World Wide Web).</CODE>
     * 
     * <BR /><BR />What is JPG? What Opens a JPG? Exact Link:
     * 
     * <BR /><BR /><A HREF="http://whatis.techtarget.com/fileformat/JPG-JPEG-bitmap" TARGET=_blank>
     * http://whatis.techtarget.com/fileformat/JPG-JPEG-bitmap</A>
     */
    JPG("jpg", "jpeg"),

    /** 
     * Used to indicate a picture using the common ommon {@code '.gif'} image format.
     * Short for <CODE><B>"Graphics Interchange Format".</B></CODE>
     */
    GIF("gif"),

    /**
     * Used to indicate a picture using the common ommon {@code '.bmp'} image format.
     * Abbreviation of the word <CODE><B>'Bit Map'</B></CODE>
     */
    BMP("bmp"),

    /**
     * Used to indicate a picture using the common {@code '.png'} image format.
     * <CODE><B>PNG</B></CODE> stands for <CODE><B>Portable Network Graphics.</B></CODE>
     * It is an open source file extension for raster graphics files. 
     */
    PNG("png");

    /** This is the actual file-name extension saved as a {@code String}.  */
    public final String extension;

    /**
     * Convert an instance of this enumerated-type to a {@code String}.
     * @return The image-format extension as a {@code String}.
     */
    public String toString() { return extension; }

    private final String alternateExtension;

    private IF(String extension)
    {
        this.extension          = extension;
        this.alternateExtension = null;
    }

    private IF(String extension, String alternateExtension)
    {
        this.extension          = extension;
        this.alternateExtension = alternateExtension;
    }

    private static final IF[] arr = { JPG, GIF, BMP, PNG };

    /**
     * This will extract the file-extension from an image {@code URL}.  Not all images on the
     * internet have {@code URL's} that end with the actual image-file-type.  In that case, or in
     * the case that the {@code 'urlStr'} is a pointer to a non-image-file, {@code 'null'} will
     * be returned.
     * @param urlStr Is the {@code url} of the image. 
     * @return If extension has a file-extension that is listed in the {@code IF[]} Array - that
     * file-extension will be returned, otherwise {@code 'null'} will be returned.
     */
    public static IF getGuess(String urlStr)
    {
        if (urlStr == null)                 return null;

        int pos = urlStr.lastIndexOf(".");

        if (pos == -1)                      return null;
        if (pos == urlStr.length() - 1)     return null;

        String s = urlStr.substring(pos + 1).toLowerCase().trim();

        for (int i=0; i < arr.length; i++)
            if (arr[i].extension.equals(s))                 return arr[i];
            else if (arr[i].alternateExtension != null)
                if (arr[i].alternateExtension.equals(s))    return arr[i];

        return null;		
    }

    /**
     * Converts a {@code String} image-extension to an instance this enumerated type.
     * @param extension A valid image-format extension
     * @return An instance of this enumeration, if applicable, or {@code 'null'} otherwise.
     */
    public static IF get(String extension)
    {
        extension = extension.toLowerCase();
        for (int i=0; i < arr.length; i++)
            if (arr[i].extension.equals(extension))                 return arr[i];
            else if (arr[i].alternateExtension != null)
                if (arr[i].alternateExtension.equals(extension))    return arr[i];
        return null;
    }

    /**
     * This will retrieve the image name from a {@code java.net.URL} object.
     * @param url The {@code url} of the image. 
     * @return If this {@code URL} has a file-extension that is listed in the {@code IF[]} Array,
     * that file-extension will be returned, otherwise {@code 'null'} will be returned.
     */
    public static IF getGuess(URL url)
    { String f = url.getFile(); if (f != null) return getGuess(f); else return null; }


    /**
     * This will parse a {@code 'Base64' String} into two groups using Java's RegEx Tools.
     *
     * <BR /><DIV STYLE="EXAMPLE">{@code
     * Matcher m = B64_INIT_STRING.matcher(base64String);
     * if (m.find()) 
     * }</DIV>
     * 
     * <BR /><BR /><OL CLASS="JDUL">
     * <LI>{@code m.group(1) => } Image Encoding Type ({@code gif, jpg,} etc...)<BR /><BR /></LI>
     * <LI>{@code m.gropu(2) => } Base 64 {@code String}<BR /></LI>
     * </OL>
     */
    public static final Pattern B64_INIT_STRING = Pattern.compile(
        "^\\s*data:\\s*image\\/\\s*([A-Za-z]{3,4})\\s*;\\s*base64\\s*,(.*)$",
        Pattern.CASE_INSENSITIVE
    );

    /**
     * This will retrieve a Buffered Image from a {@code String} retrieved from a string that
     * follows this format below.  This is the format usually found inside HTML Image Tags.
     * 
     * <BR /><BR /><B>SPECIFICALLY: </B><SPAN STYLE="color: green;">
     * {@code <IMG SRC="data:image/{png or gif or jpg etc};base64,...">}</SPAN>
     * 
     * <BR /><BR />The ellipsis (...) above represents the actual {@code Base-64} encoded
     * {@code String}.  Many web-sites return HTML image tags with the actual picture/image encoded
     * into a {@code String} and saved inside the {@code 'SRC'} attribute.  This method will decode
     * that image-as-a-{@code String} into a {@code java.awt.image.BufferedImage}
     * 
     * @param base64EncodedImageWithFormat The best way to obtain this {@code String} is to use the
     * command [{@code String encoded = imageTag.AV("src"); }], and pass this variable
     * {@code 'encoded'} to this parameter.  It is important to note that variable
     * {@code 'imageTag'} must be a {@code public class TagNode}, and that {@code TagNode} must:
     * 
     * <BR /><BR /><UL CLASS="JDUL">
     *  <LI>Have {@code public final String tok} equal to {@code 'img'}
     *      <BR /><BR /></LI>
     *  <LI>The {@code <IMG>} represented must have a {@code SRC="..."} which contains a 
     *      {@code Base-64} encoded image.
     *      <BR />
     *  </LI>
     * </UL>
     * 
     * @return A decoded image that can be saved to file, and an instance of {@code IF} that
     * identifies what type of image was specified.
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI>{@code Ret2.a} (BufferedImage):} The Converted Image
     *      <BR /><BR /></LI>
     * <LI>{@code Ret2.b} (IF):} The Image Type
     *      <BR /></LI>
     * </UL>
     */
    public static Ret2<BufferedImage, IF>
        decodeBase64ToImage(String base64EncodedImageWithFormat)
    {
        // sourceData = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPAAAADwCAYAAAA+VemSAAAgAEl...==';
        Matcher m = B64_INIT_STRING.matcher(base64EncodedImageWithFormat);

        // System.out.println("first 50:\t" + base64EncodedImageWithFormat.substring(0, 80));

        if (! m.find()) return null;
 
        String  imageFormatStr      = m.group(1);
        String  base64EncodedImage  = m.group(2);
        IF      imageFormat         = (imageFormatStr != null) ? IF.get(imageFormatStr) : null;

        // System.out.println("imageFormatStr:\t" + '[' + imageFormatStr + ']');
        // System.out.println("imageFormat:\t" + '[' + imageFormat + ']');

        if (imageFormat == null)            return null;

        BufferedImage   bi      = decodeBase64ToImage(base64EncodedImage, imageFormat);
        // BufferedImage   bi   = decodeBase64ToImage_V2(base64EncodedImage, imageFormat);

        if (bi == null)                     return null;

        return new Ret2<BufferedImage, IF>(bi, imageFormat);
    }

    /**
     * This will decode a {@code Base-64 String} into an image.  Here, the decoder used is the one
     * obtained from a call to: {@code java.util.Base64.getDecoder() }.
     *
     * <BR /><BR /><B>COPIED FROM</B> {@code java.util.Base64:}
     * 
     * <BR /><BR /><B>Basic: </B> Uses "The Base64 Alphabet" as specified in <I><B>Table 1 of RFC
     * 4648 and RFC 2045</B></I> for encoding and decoding operation. The encoder does not add any
     * line feed (line separator) character. The decoder rejects data that contains characters
     * outside the base64 alphabet.
     *
     * @return A decoded image that can be saved to file.
     */
    public static BufferedImage decodeBase64ToImage(String base64EncodedImage, IF imageFormat)
    {
        try
        {
            ByteArrayInputStream    bis     = new ByteArrayInputStream(Base64.getDecoder().decode(base64EncodedImage));
            BufferedImage           image   = ImageIO.read(bis);

            bis.close();
            return image;
        }
        catch (IOException e) { return null; }
    }

    /**
     * This will decode a base-64 String into an image.  Here, the decoder used is the one obtained
     * from a call to: {@code java.util.Base64.getURLDecoder() }.
     *
     * <BR /><BR /><B>COPIED FROM</B> {@code java.util.Base64:}
     * 
     * <BR /><BR /><B>URL and Filename safe: </B> Uses the "URL and Filename safe Base64 Alphabet"
     * as specified in <B><I>Table 2 of RFC 4648</B></I> for encoding and decoding. The encoder
     * does not add any line feed (line separator) character. The decoder rejects data that
     * contains characters outside the base64 alphabet.
     *
     * @return A decoded image that can be saved to file.
     */
    public static BufferedImage decodeBase64ToImage_V2(String base64EncodedImage, IF imageFormat)
    {
        try
        {
            ByteArrayInputStream    bis     = new ByteArrayInputStream(Base64.getUrlDecoder().decode(base64EncodedImage));
            BufferedImage           image   = ImageIO.read(bis);

            bis.close();
            return image;
        } 
        catch (IOException e) { return null; }
    }
}