NgxImageMosaic

This library provides a mosaic view of a set of images, with shaping options.

This library was generated with Angular CLI version 9.1.7.

Examples/Demo

A simple example of this library can be found in the src/app directory of this respository. You can run it by:

1. Cloning the repository;
2. Installing the dependencies running npm install;
3. Running ng serve on Angular 9;
4. Navigating to localhost:4200.

Installation

Install the package

npm install ngx-image-mosaic

Usage

You must first import the ngx-image-mosaic module.

import { NgxImageMosaicModule } from 'ngx-image-mosaic';

@NgModule({
  ...,
  imports: [
    NgxImageMosaicModule,
    ...]
})

Then, you can create objects that you will use to configure your component, using interfaces provided by the library

import {
  Frame,
  ImageMosaicParameters,
  InputImageParameters,
} from 'ngx-image-mosaic';

@Component({
  ...
})
export class MyComponent {
  frame: Frame = { height: ..., width: ... };
  inputImageParametersList: InputImageParameters[] = ...;
  options: ImageMosaicParameters = ...;

  ...

  imageSelected(path: string) {
    ...
  }
}

and finally add the ngx-image-gallery component in your html file.

<ngx-image-mosaic
  [frame]="frame"
  [inputImageParametersList]="inputImageParametersList"
  [options]="options"
  (imageSelected)="imageSelected($event)"
></ngx-image-mosaic>

API

Description of ngx-image-mosaic component.

<ngx-image-mosaic
  [frame]="frame"
  [inputImageParametersList]="inputImageParametersList"
  [options]="options"
  (imageSelected)="imageSelected($event)"
></ngx-image-mosaic>

@Inputs()

There are 3 inputs, depending on 3 interfaces :

• frame: Frame [required]

  Shape of the component.

  interface Frame = {
    height: number;
    width: number;
  }

  | Key | Type | Required | Description | | ------ | ---------------- | -------- | ------------------------------------------------ | | height | positive integer | Yes | Number of pixels for the height of the component | | width | positive integer | Yes | Number of pixels for the width of the component |

  Example:

  let frame = { width: 40, height: 30 };

• inputImageParametersList: InputImageParameters[] [required]

  Images with their own parameters.

  interface OptionalInputImageParameters {
    textHover?: string;
  }
  
  interface InputImageParameters {
    path: string;
    optionalParameters?: OptionalInputImageParameters;
  }

  | Key | Type | Required | Description | | ------------------ | ---------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------- | | path | string | Yes | Path of the image (in angular project or on the web) | | optionalParameters | OptionalInputImageParameters | Optional, default: {textHover: ""} | Gather all optional parameters about this image | | textHover | string | Optional, default: "" | Text to show when a pointer is over the image (this option must be enabled in general options) |

  Example:

  let inputImageParametersList = [
    {
      path: "gallery.org/image1",
      optionalParameters: {
        textHover: "This is image 1!",
      },
    },
    {
      path: "assets/image2",
    },
  ];

• options: ImageMosaicParameters [not required]

  Global options for the component.

  interface ImageMosaicParameters {
    imageMargin?: number;
    fillingDirection?: "vertically" | "horizontally";
    imageArea?: number;
    reductionFactor?: number;
    augmentationFactor?: number;
    reduceLength?: boolean;
    showDescriptionHover?: boolean;
  }

  | Key | Type | Required | Description | | -------------------- | ------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | imageMargin | positive integer | Optional, default: 0 | Margin in pixels for all images | | fillingDirection | "vertically" or "horizontally" | Optional, default: "horizontally" | In 'horizontally' mode, the mosaic is constructed row by row; in 'vertically' mode, the mosaic is constructed column by column | | imageArea | positive integer | Optional, default: 0 | Standard area for images in px*px (if they are big enough, they are reduced to match this area while keeping their aspect ration). If 0 is given, images will keep their orginal shape | | reductionFactor | integer between 0 and 1 | Optional, default: 0.4 | The algorithm can reduce each image to produce a better looking mosaic, by multiplying its height and its width by this reductionFactor | | augmentationFactor | positive integer | Optional, default: 0.4 | The algorithm can enlarge each image to produce a better looking mosaic, by multiplying its height and its width by (1 + augmentationFactor) | | reduceLength | boolean | Optional, default: false | The width (resp. height) of the component is reduced in horizontal (resp. vertical) mode if there is some place left. This option let you put all your images in a component with an appropriate shape | | showDescriptionHover | boolean | Optional, default: false | If true, shows a text on a photo when a pointer is above it (see textHover in image options) |

  Example:

  let options = {
    imageMargin: 5,
    fillingDirection: "horizontally",
    imageArea: 10000,
    reductionFactor: 0,
    augmentationFactor: 0.6,
    reduceLength: true,
    showDescriptionHover: false,
  };

Output()

There is one output:

• imageSelected: EventEmitter<string>

  When a photo is clicked, this output emits the path of the photo.

Additional information

• This component enlarge images only if they are big enough (images displayed will always have a smaller shape than their real one).
• If an augmentation factor greater than 0 is provided, all images are resized to never be pixelated. So their heights and width are divided by max(1 + augmentationFactor, areaFactor), where areaFactor = max(1, photoArea/imageArea) is linked to the imageArea option (see general options input).
• The time complexity of this algorithm is O(n*n) as long as the height (resp. the width) of the frame isn't to big in comparison with its width (resp. its height) in horizontal (resp. vertical) mode.

Copyrights

Integrate or build upon it for free in your personal or commercial projects. Don't republish, redistribute or sell "as-is". You can contact me at [email protected].