Module: Image Slideshow

The MMM-ImageSlideshow module is designed to display images, one at a time on a fixed interval, from one or many directories. These images can be shown in order or at random, one directory at a time or all at time. The image heights and widths can be fixed or scaled and the images can be made to be shown in grayscale.

This fork has additional 'switches' offering alternate control over the displayed image.
Notably:

• The image name and path can be displayed
  
• The image can be scaled down to fit within a region, whilst maintaining image aspect ratio (aka - best image size for display region)

Dependencies / Requirements

This module requires no special dependencies. The only requirement is that the image directories path are fixed paths accessible to the Magic Mirror instance.

Operation

This module will take in a list of directory paths, one or more, containing image files. The module will display those images in either alphabetical or random order, across either each path one at time or across all the paths at once. Once all the images have been shown, it will loop back and start again.

Extra configurations include setting the amount of time an image is shown for, rendering the images in grayscale, selecting which file extensions are valid, and using a fixed image height and/or width.

Using the module

Note - Raspberry Pi focussed: Use Git to download this extension to Magic Mirror. Make sure Git is installed on your system.
In the command line/terminal, e.g.
sudo apt install git

Next, go to the modules directory of the your Magic Mirror e.g.
cd /home/pi/MagicMirror/modules

Run (for this repository):
git clone https://github.com/OneOfTheInfiniteMonkeys/MMM-ImageSlideshow.git

The advantage of using Git is when there is an update, you can run 'git pull' and it will pull down all the updates. Magic Mirror can even let you know when there are updates.

When installed, to use this module you need to add an entry to the modules array in the config/config.js file. (RASPI path is /home/pi/MagicMirror/config/config.js) :

modules: [
	{
		module: 'MMM-ImageSlideshow',
		position: 'middle_center',
		config: {
			imageStyleString: "object-fit: scale-down; width: 800px; height: 900px;", // best image scaling within sizes
		        PathStyleText: 'nameonly',                                                // display the image file name only
			imagePaths: ['modules/MMM-ImageSlideshow/exampleImages'],                 // relative path to image files
		}
	}	
]

A different image folder may be used by changing the path entry under the entry imagePaths, held in the config.js file (excerpt shown above). If required change the array parameter on the line containing the imagePaths entry.
e.g. imagePaths: ['modules/MMM-ImageSlideshow/myimages01', 'modules/MMM-ImageSlideshow/myimages02'].
Hint: take care to use the correct punctuation and number of tabs in the config.js file.

Note - Raspberry Pi focussed: e.g. the location on a raspbery pi is typically: /home/pi/MagicMirror/config/config.js

Configuration options

The following properties can be configured:

Option	Description
imageStyleString	A CSS string which is applied to the image to be displayed. Example: 'imageStyleString: "object-fit: scale-down; width: 800px; height: 900px;",' Default value: Empty string (no effect) This value is OPTIONAL Where '"object-fit: scale-down;' causes an image to scale within the defined dimensions and width: 800px; height: 900px;", defines the size in px that the image will be fitted within, without distortion. See CSS https://www.w3schools.com/css/css3_object-fit.asp for examples
PathStyleText	A string of either 'none', 'nameonly', 'nameonlyandindex','nameonlyindexandtotal', 'fullname', 'fullpath', 'index' or 'indexandtotal' to control the image path/name text content displayed. Example: 'nameonly' Default value: 'none' This value is OPTIONAL The following are options for this parameter: 'none' No text is displayed 'nameonly' Image name (no text following . character) 'nameonlyandindex' Shows image name and image index number 'nameonlyindexandtotal' Shows image name and total number of images 'fullname' Shows image name with file extension 'fullpath' Shows full image path and image name 'index' Shows image index 'indexandtotal' Shows image index and total number of images
ImgTitleTextPos	An integer value of 0 or 1 to control positioning of image path/name text. Example: 0 Default value: 0 This value is OPTIONAL Where 0 places the image path/name text above the image, 1 places the image path/name text below the image
ImgTitleTextStyle	A CSS text format string. See /home/pi/MagicMirror/css/main.css etc. Default value is 'bright small light'. Example: 'bright medium light' Default value: 'bright small light' This value is OPTIONAL
imagePaths	Array value containing strings. Each string should be a path to a directory where image files can be found. Example: ['modules/MMM-ImageSlideshow/example1'], This value is REQUIRED
slideshowSpeed	Integer value, the length of time to show one image before switching to the next, in milliseconds. Example: 6000 Default value: 10000 This value is OPTIONAL
delayUntilRestart	Integer value, the length of time to restart the slideshow after the last image has been shown, in milliseconds. The module will go blank will waits to restart. This value defaults to zero, meaning no delay until restarting. Example: 6000 Default value: 0 This value is OPTIONAL
fixedImageWidth	Integer value, sets a fixed pixel width for all the images to be shown. If set to 0, the image's actual width is used. Example: 250 Default value: 0 This value is OPTIONAL
fixedImageHeight	Integer value, sets a fixed pixel height for all the images to be shown. If set to 0, the image's actual height is used. Example: 300 Default value: 0 This value is OPTIONAL
randomizeImageOrder	Boolean value, if true will randomize the order of the images, if false will use an alphabetical sorting by filename. Example: true Default value: false This value is OPTIONAL
treatAllPathsAsOne	Boolean value, if true will treat all the paths specified in imagePaths as one path. Otherwise, if false, images will only be shown from one path at a time in the order of imagePaths, until all the images in that path are exhausted, before continuing to the next path. Example: true Default value: false This value is OPTIONAL
makeImagesGrayscale	Boolean value, if true images will be rendered in grayscale (i.e black and white) instead of color. If false they will be rendered as just they are without change. Example: true Default value: false This value is OPTIONAL
validImageFileExtensions	String value, a list of image file extensions, seperated by commas, that should be included. Files found without one of the extensions will be ignored. Example: 'png,jpg' Default value: 'bmp,jpg,gif,png' This value is OPTIONAL