Metadata-Version: 2.1
Name: imagegengan
Version: 1.0.2
Summary: A plug-and-play GAN image generator.
Home-page: https://github.com/anthonykrivonos/imagegengan
Author: Anthony Krivonos
Author-email: info@anthonykrivonos.com
License: UNKNOWN
Description: # 🌄 imagegengan
        
        > A plug-and-play GAN image generator using a Keras/Tensorflow backend. [1]
        
        ## ⬇️ Installation
        
        `pip install imagegengan`
        
        ## ✨ Features
        
        - Completely plug-and-play DCGAN implementation. [2]
        - Takes images *of any dimensions* as inputs and outputs to the dimensions of your choice.
        - Supports custom generative and discriminative models, if you need that.
        - Built-in image augmentation to mitigate effects of small training datasets.
        
        
        ## 🏃‍♂️ Quick Start
        
        ```
        from imagegengan import imagegengan
        
        # This is a relative path to a directory containing
        # a ton of different-sized images.
        images_dir = "dog_images/"
        
        # These are the dimensions of our generated image.
        # The third dimension is the # of channels, so use
        # 3 for a color (RGB) image and 1 for grayscale.
        img_shape = (200, 200, 3)
        
        # Create the image generator.
        image_generator = imagegengan(img_shape=img_shape)
        
        # Train the image generator.
        image_generator.train(from_dir=images_dir, epochs=150, batch_size=32)
        
        # Generate a new image (outputs a numpy array
        # that can be displayed or saved as an image).
        generated_image = image_generator.generate()
        ```
        
        Or, without the comments:
        
        ```
        from imagegengan import imagegengan
        
        image_generator = imagegengan(img_shape=(200, 200, 3))
        image_generator.train(from_dir="dog_images/", epochs=150, batch_size=32)
        
        generated_image = image_generator.generate()
        ```
        
        ## 📖 Documentation
        
        ### `imagegenrnn` Class
        
        ##### `__init__(...)`
        
        Initializes a new imagegenrnn object.
        
        - **`img_shape`**: The image shape as a three-dimensional tuple (height, width, channels). (default `(224, 224, 3)`)
        - **`generator`**: The generator model to use. (default `Generator.Default`)
        - **`discriminator`**: The discriminator to use. (default `Discriminator.Default`)
        - **`upsample_layers`**: The sequence of layers for upsampling in the generator and downsampling in the discriminator. (default `[1024, 512, 256, 128, 64]`)
        - **`kernel_size`**: The kernel size for convolutions in the GAN. 5x5 is the standard so we advise against changing this. (default `(5, 5)`)
        - **`noise_depth`**: The length of the input noise vector. 100 is the standard so we advise against changing this. (default `100`)
        - **`lr`**: The learning rate of both the generator and discriminator. (default `0.00015`)
        
        #### `train(...)`
        
        > Train the GAN model on either images from a directory, images from a list, or images preprepared with the imagegengan.prepare_images function. Only one of such inputs must be provided.
        
        - **`from_dir`**: The directory to train from. The images here can be different sizes and the resizing function will standardize them. Do not supply from_list or from_prepared if you choose to train from a directory. (default `None`)
        - **`from_list`**: A numpy list containing *unprepared* images to train from. The images here can be different sizes and the resizing function will standardize them. Do not supply from_dir or from_prepared if you choose to train from a list. (default `[]`)
        - **`from_prepared`**: A numpy list or string .npy filename containing *prepared* images using the imagegengan.prepare_images function. The images here *must* be the same size as the image shape of the imagegengan class. Do not supply from_dir or from_list if you choose to train from a prepared list. (default `[]`)
        - **`epochs`**: The number of epochs to train on. (default `100`)
        - **`batch_size`**: The size of each training batch. Must be less than or equal to the number of input images. It is advised to keep this number small (~8) to avoid tensor overflows. (default `8`)
        - **`lr`**: The learning rate of the GAN (not of the generator or discriminator that were initialized in the constructor). Defaults to the generator's and discriminator's learning rate. (default `None`)
        - **`noise_level`**: The coefficient of noise when training the discriminator. (default `0.2`)
        - **`save_interval`**: The interval (in epochs) of saving the GAN to a file. If save_to is not None, defaults to 1/10th of the number of epochs. (default `None`)
        - **`save_to`**: The directory to save to on the save_interval. If None, the GAN is not saved. (default `None`)
        - **`grayscale`**: Boolean indicating whether or not the images should be converted into grayscale. (default `False`)
        - **`verbose`**: Boolean indicating whether the training's status should be outputted. (default `True`)
        - **`resizing`**: The resizing method. Use Resizing.CONTAIN or 0 to pad the images, Resizing.STRETCH or 1 to stretch the images and ignore aspect ratio, and Resizing.COVER or 2 to crop the images while maintaining aspect ratio. (default `Resizing.COVER`)
        - **`padding_color`**: The color of the padding used if the resizing mode is Resizing.CONTAIN or 0. Defaults to 0, which is black. (default `0`)
        - **`horizontal_flip`**: Boolean indicating whether the training images can be horizontally flipped during image data augmentation. This helps the GAN generator more kinds of images. (default `False`)
        - **`seed`**: Integer seed for the random image augmenter. (default `1`)
        - **`rounds`**: Number of rounds to go through during image augmentation. The more rounds, the longer it takes to train, but the more results yielded. (default `1`)
        - **`limit`**: Limits the number of training images used, mainly for debugging or retraining purposes. (default `None`)
        - **`shuffle`**: Boolean indicating whether or not to shuffle the training images. Often helpful during retraining. (default `False`)
        
        #### `generate(...)`
        
        > Generate a single image or a batch of images in numpy format.
        
        - **`num_outputs`**: The number of images to output. If  1, returns a single image. Otherwise, returns an array of images. (default `1`)
        - **`save_to_dir`**: The directory to save the images to, if not None. (default `None`)
        - **`file_prefix`**: The prefix of the generated image files. Does not do anything if save_to_dir is None. (default `"generated_img"`)
        - **`verbose`**: Boolean indicating whether the status of image generation should be outputted. (default `True`)
        
        **`returns`** A single numpy array output image or a list of such images.
        
        #### `save(...)`
        
        > Save the imagegengan to a .h5 file. Use like `gen.save('myfile')`.
        
        - **`filename`**: The name of the file to save the image as.
        
        #### `load(...)`
        
        > Load the imagegengan from a .h5 file. Use like `gen.load('myfile')`.
        
        - **`filename`**: The name of the file to load the image from.
        
        #### `prepare_images(...)`
        _(static method)_
        
        > Creates a numpy image list of resized images from either images from a directory or images from a list. Only one of such inputs must be provided.
        
        - **`img_shape`**: The image shape as a three-dimensional tuple (height, width, channels).
        - **`from_dir`**: The directory to train from. The images here can be different sizes and the resizing function will standardize them. Do not supply from_list or from_prepared if you choose to train from a directory. (default `None`)
        - **`from_list`**: A numpy list containing *unprepared* images to train from. The images here can be different sizes and the resizing function will standardize them. Do not supply from_dir or from_prepared if you choose to train from a list. (default `[]`)
        - **`save_to_npy`**: A string filename to where the numpy array output can be saved. Saving prepared images to a .npy file and inputting these images into imagegengan.train using from_prepared is the recommended (but not easiest) training method. If None, the output images are not saved. (default `None`)
        - **`verbose`**: Boolean indicating whether the image preparation status should be outputted. (default `True`)
        - **`grayscale`**: Boolean indicating whether or not the images should be converted into grayscale. (default `False`)
        - **`resizing`**: The resizing method. Use Resizing.CONTAIN or 0 to pad the images, Resizing.STRETCH or 1 to stretch the images and ignore aspect ratio, and Resizing.COVER or 2 to crop the images while maintaining aspect ratio. (default `Resizing.COVER`)
        - **`padding_color`**: The color of the padding used if the resizing mode is Resizing.CONTAIN or 0. Defaults to 0, which is black. (default `0`)
        - **`limit`**: Limits the number of training images used, mainly for debugging or retraining purposes. (default None)
        - **`shuffle`**: Boolean indicating whether or not to shuffle the training images. Often helpful during retraining. (default `False`)
        
        **`returns`** A numpy array of prepared images that are all the same size.
        
        ## 📄 Changelist
        
        #### 1.0.0
        - Initial work; used [Tiago Freitas's implementation](https://github.com/tensorfreitas/DCGAN-for-Bird-Generation/blob/master/traindcgan.py), [Mitchell Jolly's implementation](https://github.com/mitchelljy/DCGAN-Keras), and [this issue on ImageDataGenerator flows](https://github.com/keras-team/keras/issues/2694#issuecomment-218446360) for reference.
        
        
        ## 📚 References
        
        [1] Chollet, Francois et al. "Keras." https://keras.io. (2015).
        
        [2] Alec Radford, et al. "Unsupervised Representation Learning with Deep Convolutional Generative Adversarial Networks." (2015).
        
        
        ## Author
        
        Anthony Krivonos ([Portfolio](https://anthonykrivonos.com) | [LinkedIn](https://linkedin.com/in/anthonykrivonos))
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.7
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
