# @badskuns/10101-art-image-viewer

> The "10101-art-image-viewer" library is a simple and lightweight tool for displaying images with zooming and panning functionality. The library is designed to be easy to use and customizable, with a minimal API and no external dependencies.

Latest version **1.0.3** (published 2023-11-24) · 0 weekly downloads

## Install

```sh
npm install @badskuns/10101-art-image-viewer
pnpm add @badskuns/10101-art-image-viewer
yarn add @badskuns/10101-art-image-viewer
bun add @badskuns/10101-art-image-viewer
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2023-11-24 |
| First published | 2023-04-20 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 3.7 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | badskuns |

## Links

- npm: https://www.npmjs.com/package/@badskuns/10101-art-image-viewer
- npm.io page: https://npm.io/package/@badskuns/10101-art-image-viewer

## Dependencies (5)

- [pixi.js](https://npm.io/package/pixi.js.md) ^7.2.4
- [@pixi/react](https://npm.io/package/@pixi/react.md) ^7.0.3
- [pixi-viewport](https://npm.io/package/pixi-viewport.md) ^5.0.1
- [lodash.debounce](https://npm.io/package/lodash.debounce.md) ^4.0.8
- [@tweenjs/tween.js](https://npm.io/package/@tweenjs/tween.js.md) ^19.0.0

## Recent versions

- 1.0.3 (latest) — 2023-11-24
- 1.0.2-next.9 (beta) — 2023-11-24
- 1.0.2-next.8 — 2023-11-24
- 1.0.2-next.7 — 2023-04-30
- 1.0.2-next.6 — 2023-04-26
- 1.0.2-next.5 — 2023-04-26
- 1.0.2-next.4 — 2023-04-26
- 1.0.2-next.3 — 2023-04-26
- 1.0.2-next.2 — 2023-04-20
- 1.0.2-next.1 — 2023-04-20
- 1.0.2-next.0 — 2023-04-20
- 1.0.1 — 2023-04-20
- 1.0.1-beta.1 — 2023-04-20
- 1.0.0 — 2023-04-20

## README

# 10101 Art Image Viewer

The "10101-art-image-viewer" library is a simple and lightweight tool for displaying images with zooming and panning functionality. The library is designed to be easy to use and customizable, with a minimal API and no external dependencies.


# Dev mode

## Installation

```bash
yarn
```

## Start
```bash
npm start
```

## Beta publish
```bash
npm run beta
```

## Publish
```bash
npm publish
```

# Usage

## Installation

```bash
yarn add @badskuns/10101-art-image-viewer
```

## Usage

```tsx
import React from 'react';
import ArtImageViewer from '@badskuns/10101-art-image-viewer';

const MyComponent = () => {
  const src = 'https://example.com/image.jpg';
  const containerSize = { width: 800, height: 600 };
  const sourceSize = { width: 1600, height: 1200 };
  const baseFragment = null // any fragment that could be used as data anchestor of fragment
  const data: TokenFragment = [
    { tokenId: 'abc', left: 200, top: 200, width: 100, height: 100, filterColor: '#fff', filterOpacity: 0.3, baseFragment: baseFragment }
  ];

  return (
    <ArtImageViewer
      src={'./image.jpg'}
      containerSize={{width: '100vw', height: '100vh'}}
      sourceSize={{width: 1920, height: 1080}}
      data={data}
      hoverData={null}
      onHover={(fragment) => console.log(fragment)}
      onClick={(fragment) => console.log(fragment)}
      renderLoader={() => <div>Loading...</div>}
      focusData={null}
      freezeData={null}
    />
  );
};
```

## Props

- `src`: string (required) - the source url of the image to display.
- `containerSize`: `SizeType` (required) - the size of the container element as an object of `{ width, height }`.
- `sourceSize`: `SizeType` (required) - the size of the original image as an object of `{ width, height }` to recompute initial coordinates. Exist because downloaded image has different size from source image coordinates received.
- `data`: `TokenFragment<>[]` (optional) - an array of objects representing labels to display on the image on hover or focus. Each object should have the properties `label` (string) and `position` (array of `[x, y]` coordinates).
- `hoverData`: `ImageViewerMouseEvent` (optional) - an object representing the label to display on hover. Should have the properties `label` (string) and `position` (array of `[x, y]` coordinates).
- `onHover`: function (optional) - a callback function to be called when the mouse is hovering over a label. Receives the data object for the label as an argument.
- `onClick`: function (optional) - a callback function to be called when a label is clicked. Receives the data object for the label as an argument.
- `renderLoader`: function (optional) - a function that returns a React element to be displayed while the image is loading.
- `focusData`: `ImageViewerMouseEvent` (optional) - an object representing the label to display on focus. Should have the properties `label` (string) and `position` (array of `[x, y]` coordinates).
- `freezeData`: `ImageViewerMouseEvent` (optional) - an object representing the label to display when the image is frozen. Should have the properties `label` (string) and `position` (array of `[x, y]` coordinates).

# Basic description
This project was crated to resolve html dom limitations in rendering of thousands of elements. We are using canvas and canvas wrapper library pixi to render block elements.
Because of pixi limitations of drawings amount that lead to performance degradation, we split drawing elements in different components and canvas layers

``FragmentsToken`` - main layer responsible for filling blocks with parts of the image
``FragmentsBackground`` - responsible to fill viewport on focus
``FragmentsFill`` - responsible for filling blocks in different colors based on config
``FragmentsGrid`` - responsible for grid drawing around each block
``HoveredFragment`` - responsible for drawing animation of fragment hover
``NavigationControls`` - responsible for drawing scale and zoom progress bars 

``EventsWrapper`` - layer responsible for detecting mouse events and computations of intersections of fragments with mouse coordinates, dynamic logic includes scalable offsets on zoom  

`useZoomAnimationDraw` - one of the most important parts of the logic. It's responsible for positioning and calculations for all fragments of viewport and provide logic of scaling and offsetting blocks during zoom 



## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---
_Source: https://npm.io/package/@badskuns/10101-art-image-viewer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._