@abidibo/react-cam-roi 0.0.7 → 0.0.8

package/README.md

@@ -4,15 +4,152 @@
 
 This is a react component which lets you draw regions of interest (ROI) over images, manage metadata and import/export everything.
 
+Metadata are dynamic information that can be attached to the whole image or to each ROI. The ROI that can be drawn, and the metadata are controlled through a configuration object.
+
+![Screenshot](./react-cam-roi.png)
+
+It provides one component: `RoiEditor` and one provider: `UiProvider`. The editor lets you draw regions of interest over a given image (url). Each has dynamic metadata attached (configured via api).
+Export and import functionality is also provided.
+
+Features:
+
+- Autosizing of the editor: the canvas resizes to the size of the image, but it's also responsive, so if the container width is smaller, then the canvas is resized accordingly keeping the aspect ratio.
+- Draw polylines, polygons and rectangles, change dimensions and rotate them.
+- Support for dynamic metadata information attached to each shape and the whole image.
+- Import and export shapes and metadata in json format.
+- Highly customizable: shape colors, custom components and css classes.
+
 ## Installation
 
 ```
-npm install react-cam-roi
+npm install @abidibo/react-cam-roi
 ```
 
 ## Usage
 
-TODO
+```ts
+import { RoiEditor, UiProvider } from '@abidibo/react-cam-roi'
+import { Typography, IconButton, Delete } from '@mui/material'
+
+const MyComponent: React.FC = () => {
+    const themMode = 'light'
+    const config = {} // se below
+
+    return (
+        <UiProvider themeMode={themeMode} IconButton={IconButton} Typography={Typography} DeleteIcon={() => <Delete />}>
+          <RoiEditor imageUrl={'https://placecats.com/800/600'} configuration={config} />
+        </UiProvider>
+    )
+}
+```
+
+## Configuration
+
+The configuration prop defines which kind and how many ROIs can be drawn, along with metadata information. Here the types definitions and an example:
+
+```ts
+// All types can be imported:
+// import { Types } from '@abidibo/react-cam-roi'
+// const { ToolEnum, ShapeType, DataTypeEnum, OperatorEnum, ConfigurationParameter, RoiConfiguration, Configuration } = Types
+
+export const enum ToolEnum {
+  Pointer = 'pointer',
+  Polyline = 'polyline',
+  Polygon = 'polygon',
+  Rectangle = 'rect',
+}
+
+export type ShapeType = ToolEnum.Polyline | ToolEnum.Polygon | ToolEnum.Rectangle
+
+export enum DataTypeEnum {
+  Integer = 'int',
+  Float = 'float',
+  String = 'string',
+  Boolean = 'bool',
+}
+
+export enum OperatorEnum {
+  Lt = 'lt',
+  Lte = 'lte',
+  Gt = 'gt',
+  Gte = 'gte',
+  Eq = 'eq',
+}
+
+export type ConfigurationParameter = {
+  codename: string
+  label: string
+  description: string
+  unit: string
+  type: DataTypeEnum
+  options: { value: number | string | boolean; label: string }[]
+  required: boolean
+  value: number | string | boolean | null
+}
+
+export type RoiConfiguration = {
+  role: string
+  type: Omit<ShapeType, 'pointer'>
+  multiplicity: {
+    operator: OperatorEnum
+    threshold: number
+  }
+  parameters: ConfigurationParameter[]
+}
+
+export type Configuration = {
+  parameters: ConfigurationParameter[]
+  rois: RoiConfiguration[]
+}
+
+export const configuration: Configuration = {
+  parameters: [
+    {
+      codename: 'analytics_1', // internal code
+      label: 'Analytics param 1', // to be shown in interface
+      description: 'This is some descriptive text', // tooltip
+      unit: 's', // unit
+      type: DataTypeEnum.Integer, // int, float, string, bool
+      options: [
+        // if filled -> enum of types type
+        {
+          value: 7,
+          label: 'Seven',
+        },
+        {
+          value: 10,
+          label: 'Ten',
+        },
+      ],
+      required: true, // true | false,
+      value: 10, // default value
+    },
+  ],
+  rois: [
+    {
+      role: 'invasion_area', // analytics role, do not show in interface
+      type: ToolEnum.Polygon,
+      multiplicity: {
+        // how many rois of this type can/should be created
+        operator: OperatorEnum.Lt, // lt | lte | gt | gte | eq
+        threshold: 2,
+      },
+      parameters: [
+        {
+          codename: 'threshold', // internal code
+          label: 'Alert threshold', // to be shown in interface
+          description: 'Threshold used for triggering alarms', // tooltip
+          unit: '%', // unit
+          type: DataTypeEnum.Integer, // int, float, string, bool
+          options: [],
+          required: true, // true / false,
+          value: null, // default value
+        },
+      ],
+    },
+  ],
+}
+```
 
 ## Customization
 
@@ -20,14 +157,14 @@ You can customize many aspects of this library by using the `UiProvider`.
 
 - You can customize both the styles and the components use in this library. The library provides default components with an interface compatible witu mui components.
 - You can override them by using the `UiProvider`. But you can also use the default ones and just add your styling.
-- You can pass a theme mode which is used by the default components to determine the color scheme. It is also used to define custom classes you can use for styling. 
+- You can pass a theme mode which is used by the default components to determine the color scheme. It is also used to define custom classes you can use for styling.
 - You can define a primary color which is used for color or background of active elements.
 - You can define custom strings used here and there.
 - You can enable logs in the console by setting the `enableLogs` option to `true`.
 
-``` tsx
-import { UiProvider, RoiEditor } from 'react-cam-roi'
+```tsx
 import IconButton from '@mui/material/IconButton'
+import { UiProvider, RoiEditor } from 'react-cam-roi'
 
 const MyView: React.FC = () => {
   return (
@@ -40,19 +177,35 @@ const MyView: React.FC = () => {
 
 ### UiProvider
 
-```ts 
+Props and types are defined later in this document.
+
+```ts
 type UiContextType = {
   children?: React.ReactNode
   enableLogs: boolean
   themeMode: 'light' | 'dark'
   primaryColor: string
   Typography: React.FC<TypographyProps>
+  Modal: React.FC<ModalProps>
   IconButton: React.FC<IconButtonProps>
   DeleteIcon: React.FC<DeleteIconProps>
   EditIcon: React.FC<EditIconProps>
   SelectIcon: React.FC<SelectIconProps>
+  notify: INotify
   strings: {
+    cannotDrawMorePolygons: string
+    cannotDrawMorePolylines: string
+    cannotDrawMoreRectangles: string
     id: string
+    mainParametersMetadata: string
+    polygon: string
+    polygonHelpText: string
+    polyline: string
+    polylineHelpText: string
+    rect: string
+    rectHelpText: string
+    pointer: string
+    pointerHelpText: string
     type: string
   }
 }
@@ -66,22 +219,55 @@ Here comes the list of components you can override using the `UiProvider`.
 
 ##### Interface
 
-``` ts 
+```ts
 type LoaderProps = {}
 ```
 
 ##### Classes
+
 - `react-cam-roi-loader`
 - `react-cam-roi-loader-light`
 - `react-cam-roi-loader-dark`
 
+#### Modal
+
+##### Interface
+
+```ts
+type ModalProps = {
+  children?: React.ReactNode
+  title: string
+  onClose: () => void
+  isOpen: boolean
+  size: 'xs' | 'sm' | 'md' | 'lg'
+}
+```
+
+##### Classes
+
+- `react-cam-roi-modal`
+- `react-cam-roi-modal-light`
+- `react-cam-roi-modal-dark`
+- `react-cam-roi-modal-overlay`
+- `react-cam-roi-modal-overlay-light`
+- `react-cam-roi-modal-overlay-dark`
+- `react-cam-roi-modal-header`
+- `react-cam-roi-modal-header-light`
+- `react-cam-roi-modal-header-dark`
+- `react-cam-roi-modal-title`
+- `react-cam-roi-modal-title-light`
+- `react-cam-roi-modal-title-dark`
+
 #### Typography
 
 ##### Interface
 
-``` ts 
+```ts
 type TypographyProps = {
   children?: React.ReactNode
+  variant?: any // compatible with mui
+  component?: any // compatible with mui
+  className?: string
 }
 ```
 
@@ -89,7 +275,7 @@ type TypographyProps = {
 
 ##### Interface
 
-``` ts 
+```ts
 type IconButtonProps = {
   children?: React.ReactNode
   onClick?: (event: React.MouseEvent) => void
@@ -100,7 +286,7 @@ type IconButtonProps = {
 
 ##### Interface
 
-``` ts 
+```ts
 type DeleteIconProps = {
   color?: string
   style?: React.CSSProperties
@@ -111,7 +297,7 @@ type DeleteIconProps = {
 
 ##### Interface
 
-``` ts 
+```ts
 type EditIconProps = {
   color?: string
   style?: React.CSSProperties
@@ -122,13 +308,45 @@ type EditIconProps = {
 
 ##### Interface
 
-``` ts 
+```ts
 type SelectIconProps = {
   color?: string
   style?: React.CSSProperties
 }
 ```
 
+#### CopyIcon
+
+##### Interface
+
+```ts
+type CopyIconProps = {
+  color?: string
+  style?: React.CSSProperties
+}
+```
+
+#### AnnotateIcon
+
+##### Interface
+
+````ts
+type AnnotateIconProps = {
+  color?: string
+  style?: React.CSSProperties
+}
+
+### Functions
+
+``` ts
+type INotify = { // compatible with toast (react-toastify)
+  info: (message: string) => void
+  warn: (message: string) => void
+  error: (message: string) => void
+  success: (message: string) => void
+}
+````
+
 ### Styles
 
 There are components that cannot be overridden. But still you can use classes to style them.
@@ -145,11 +363,21 @@ There are components that cannot be overridden. But still you can use classes to
 - `react-cam-roi-toolbar-light`
 - `react-cam-roi-toolbar-dark`
 
-#### Metadata table
+- `react-cam-roi-toolbar-spacer`
+- `react-cam-roi-toolbar-spacer-light`
+- `react-cam-roi-toolbar-spacer-dark`
+
+#### Toolbar help text
+
+- `react-cam-roi-toolbar-helper`
+- `react-cam-roi-toolbar-helper-light`
+- `react-cam-roi-toolbar-helper-dark`
 
-- `react-cam-roi-metadata-table`
-- `react-cam-roi-metadata-table-light`
-- `react-cam-roi-metadata-table-dark`
+#### Shapes list
+
+- `react-cam-roi-shapes-table`
+- `react-cam-roi-shapes-table-light`
+- `react-cam-roi-shapes-table-dark`
 
 #### Colorpicker button
 
@@ -160,3 +388,38 @@ There are components that cannot be overridden. But still you can use classes to
 - `react-cam-roi-colorpicker-button-active`
 - `react-cam-roi-colorpicker-button-active-light`
 - `react-cam-roi-colorpicker-button-active-dark`
+
+## Development
+
+After cloning the repository and install dependencies (`yarn install`), you can run the following commands:
+
+| Command          | Description           |
+| ---------------- | --------------------- |
+| `yarn clean`     | Clean the dist folder |
+| `yarn build`     | Build the library     |
+| `yarn storybook` | Run storybook         |
+
+In order to start developing just run the storybook, then make changes to code and the storybook will be updated.
+
+In order to test the library in onother local react project you can:
+
+```bash
+$ cd react-cam-roi
+$ yarn link
+$ cd ../my-project
+$ yarn link @abidibo/react-cam-roi
+```
+
+Then rebuild this library to see your changes in the project.
+
+## CI
+
+A github action pipeline is provided, it will publish the package to npm when a new tag is pushed. You need to add the `NPM_TOKEN` secret to your repository settings.
+
+Example of deployment:
+
+```bash
+$ npm version patch
+$ git push
+$ git push --tags
+```

package/dist/Components/Modal/Modal.module.css

@@ -0,0 +1,85 @@
+.modal-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  z-index: 9000;
+}
+
+.modal-overlay-light {
+  background-color: rgba(255, 255, 255, 0.7);
+}
+
+.modal-overlay-dark {
+  background-color: rgba(0, 0, 0, 0.7);
+}
+
+.modal {
+  max-width: 80%;
+  max-height: 80%;
+  overflow: auto;
+  padding: 20px;
+  border-radius: 5px;
+}
+
+.modal:focus-visible {
+  outline: none;
+}
+
+.modal-light {
+  background-color: #fff;
+  box-shadow: 0 0 10px rgba(0, 0, 0, 0.2);
+  color: #000;
+}
+
+.modal-dark {
+  background-color: #333;
+  box-shadow: 0 0 10px rgba(255, 255, 255, 0.2);
+  color: #fff;
+}
+
+.modal-xs {
+  width: 400px;
+}
+
+.modal-sm {
+  width: 600px;
+}
+
+.modal-md {
+  width: 800px;
+}
+
+.modal-lg {
+  width: 1000px;
+}
+
+.modal-xl {
+  width: 1200px;
+}
+
+.modal-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 1rem;
+}
+
+.modal-title {
+  font-size: 1.5rem;
+  font-weight: bold;
+  margin: 0;
+}
+
+.modal-title-light {
+  color: #000;
+}
+
+.modal-title-dark {
+  color: #fff;
+}
+

package/dist/Components/Modal/index.d.ts

@@ -0,0 +1,9 @@
+import { PropsWithChildren } from 'react';
+export type ModalProps = {
+    isOpen: boolean;
+    onClose: () => void;
+    title: string;
+    size: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+};
+declare const Modal: React.FC<PropsWithChildren<ModalProps>>;
+export default Modal;

package/dist/Components/Modal/index.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createPortal } from 'react-dom';
+import { useContext } from 'react';
+import CloseIcon from '../../Icons/CloseIcon';
+import { UiContext } from '../../Providers/UiProvider';
+import { css } from '../../Utils';
+import styles from './Modal.module.css';
+const Modal = ({ isOpen, onClose, children, title, size }) => {
+    const { themeMode, IconButton, Typography } = useContext(UiContext);
+    const iconColor = themeMode === 'light' ? 'black' : 'white';
+    if (!isOpen) {
+        return null;
+    }
+    return createPortal(_jsx("div", { className: css('modal-overlay', styles, themeMode), children: _jsxs("div", { className: `${css('modal', styles, themeMode)} ${css(`modal-${size}`, styles, themeMode)}`, children: [_jsxs("div", { className: css('modal-header', styles, themeMode), children: [_jsx(Typography, { component: 'h6', className: css('modal-title', styles, themeMode), children: title }), _jsx(IconButton, { onClick: onClose, children: _jsx(CloseIcon, { color: iconColor }) })] }), children] }) }), document.body);
+};
+export default Modal;

package/dist/Components/RoiEditor/Canvas.js

@@ -1,13 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useRef, useEffect } from 'react';
 import * as fabric from 'fabric';
-import { useEditorContext } from '../../Providers/EditorProvider';
 import { useDispatcherEvents, useTool } from './Hooks';
 const Canvas = ({ canvasSize }) => {
-    const { activeTool, setActiveTool, activeColor, addShape } = useEditorContext();
     const canvasRef = useRef(null);
-    useTool(activeTool, activeColor, addShape, canvasRef.current);
-    useDispatcherEvents(canvasRef.current, setActiveTool);
+    useTool(canvasRef.current);
+    useDispatcherEvents(canvasRef.current);
     useEffect(() => {
         canvasRef.current = new fabric.Canvas('react-cam-roi-canvas');
         canvasRef.current.setDimensions({ width: canvasSize.width, height: canvasSize.height });

package/dist/Components/RoiEditor/Hooks.d.ts

@@ -1,5 +1,4 @@
 import * as fabric from 'fabric';
-import { Shape, ShapeType, ToolEnum } from './Types';
 export declare const useImageSize: (imageUrl: string) => {
     imageSize: {
         width: number;
@@ -16,8 +15,8 @@ export declare const useCanvasSize: (imageUrl: string) => {
         width: number;
         height: number;
     };
-    wrapperRef: import("react").RefObject<HTMLDivElement | null>;
+    wrapperRef: import("react").RefObject<HTMLDivElement>;
     isReady: boolean;
 };
-export declare const useTool: (tool: ToolEnum, activeColor: string, addShape: (id: string, type: ShapeType, shape: Shape) => void, canvas: fabric.Canvas | null) => void;
-export declare const useDispatcherEvents: (canvas: fabric.Canvas | null, setActiveTool: (tool: ToolEnum) => void) => void;
+export declare const useTool: (canvas: fabric.Canvas | null) => void;
+export declare const useDispatcherEvents: (canvas: fabric.Canvas | null) => void;