@abidibo/react-cam-roi 0.0.7 → 0.0.10

package/README.md

@@ -2,32 +2,251 @@
 
 > Still in development!
 
-This is a react component which lets you draw regions of interest (ROI) over images, manage metadata and import/export everything.
+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 and/or to each ROI. The number of drawable ROIs can also be configured.
+
+![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 ROI can have dynamic metadata attached.    
+
+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.
+  (the size is adjusted on load, after will remain the same even if changing viewport size)
+- Draw polylines, polygons and rectangles, change dimensions and rotate them.
+- Support for number of drawable ROIs, defining a rule for each type.
+- Support for dynamic metadata information attached to each shape and the whole image (with validation included).
+- Import and export shapes and metadata in json format.
+- Highly customizable: shape colors, custom components and css classes.
 
 ## Installation
 
-```
-npm install react-cam-roi
+``` bash
+npm install @abidibo/react-cam-roi
 ```
 
 ## Usage
 
-TODO
+```ts
+import { RoiEditor, UiProvider, Types } from '@abidibo/react-cam-roi'
+import { Typography, IconButton, Delete } from '@mui/material'
+
+const MyComponent: React.FC = () => {
+    const themMode = 'light'
+    const config = {} // see below
+
+    const handleSubmit = (data: Types.Output) =>  console.log(data)
+
+    return (
+        <UiProvider themeMode={themeMode} IconButton={IconButton} Typography={Typography} DeleteIcon={() => <Delete />}>
+          <RoiEditor imageUrl={'https://placecats.com/800/600'} configuration={config} onSubmit={handleSubmit} />
+        </UiProvider>
+    )
+}
+```
+
+The `RoiEditor` props and the `Output` interface used both in import and export:
+
+``` ts 
+export type RoiEditorProps = {
+  // the url of the image we want to annotate
+  imageUrl: string
+  configuration: Configuration
+  onSubmit: (data: Output) => void
+  initialData?: Output
+}
+
+export const enum ToolEnum {
+  Pointer = 'pointer',
+  Polyline = 'polyline',
+  Polygon = 'polygon',
+  Rectangle = 'rect',
+}
+
+export type ShapeType = ToolEnum.Polyline | ToolEnum.Polygon | ToolEnum.Rectangle
+
+export type OutputShapeRect = {
+  top: number
+  left: number
+  width: number
+  height: number
+  color: string
+}
+
+export type OutputShapePolyline = {
+  points: { x: number; y: number }[]
+  top: number
+  left: number
+  color: string
+}
+
+export type OutputShapePolygon = {
+  points: { x: number; y: number }[]
+  top: number
+  left: number
+  color: string
+}
+
+
+export interface OutputParameter {
+  codename: string
+  value: number | string | boolean | string[] | number[] | null
+}
+
+export interface OutputRoi {
+  parameters: OutputParameter[]
+  type: ShapeType
+  shape: OutputShapeRect | OutputShapePolyline | OutputShapePolygon
+}
+export interface Output {
+  parameters: OutputParameter[]
+  rois: OutputRoi[]
+}
+```
+
+Take a look at the `UiProvider` allowed props (below) to see all the customization options.
+
+## 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
+
+// The drawable shapes plus the Pointer tool
+export const enum ToolEnum {
+  Pointer = 'pointer',
+  Polyline = 'polyline',
+  Polygon = 'polygon',
+  Rectangle = 'rect',
+}
+
+// Allowed shape types
+export type ShapeType = ToolEnum.Polyline | ToolEnum.Polygon | ToolEnum.Rectangle
+
+// Data types allowed for metadata values
+export enum DataTypeEnum {
+  Integer = 'int',
+  Float = 'float',
+  String = 'string',
+  Boolean = 'bool',
+}
+
+// Operators allowed for multiplicity (control how many shapes should/can be drawn)
+export enum OperatorEnum {
+  Lt = 'lt',
+  Lte = 'lte',
+  Gt = 'gt',
+  Gte = 'gte',
+  Eq = 'eq',
+}
+
+// Definition of a metadata parameter
+export type ConfigurationParameter = {
+  codename: string // unique
+  label: string // label of the parameter
+  description: string // helper text
+  unit: string // postponed to the label
+  type: DataTypeEnum // value type
+  options: { value: number | string | boolean; label: string }[] // if filled the component will be a dropdown
+  multiple?: boolean // for multiple selection
+  required: boolean // required parameter
+  value: number | string | boolean | string[] | number[] | null // default value
+}
 
-## Customization
+// Configuration of ROIs
+export type RoiConfiguration = {
+  role: string // for our use case
+  type: Omit<ShapeType, 'pointer'> // shape type
+  multiplicity: { // how many ROIs of this type can be drawn
+    operator: OperatorEnum
+    threshold: number
+  }
+  parameters: ConfigurationParameter[] // ROIs parameters for this shape type
+}
+
+// Whole configuration
+export type Configuration = {
+  parameters: ConfigurationParameter[]
+  rois: RoiConfiguration[]
+  options: {
+    hideForbiddenTools?: boolean // hide tools controllers for shapes that cannot be drawn
+    description?: string // optional initial text shown in the editor
+  }
+}
+
+// Example
+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
+        },
+      ],
+    },
+  ],
+  options?: {
+    hideForbiddenTools?: boolean,
+    description?: string,
+  }
+}
+```
+
+## UiProvider and Customization
 
 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 customize both the styles and the components used in this library. The library provides default components with an interface almost compatible witu mui components (maybe you'll need to wrap some of them).
 - 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 define custom strings used here and there (some strings require one or more placeholders).
 - You can enable logs in the console by setting the `enableLogs` option to `true`.
 
 ``` tsx
-import { UiProvider, RoiEditor } from 'react-cam-roi'
 import IconButton from '@mui/material/IconButton'
+import { UiProvider, RoiEditor } from 'react-cam-roi'
 
 const MyView: React.FC = () => {
   return (
@@ -40,19 +259,54 @@ 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>
-  IconButton: React.FC<IconButtonProps>
-  DeleteIcon: React.FC<DeleteIconProps>
-  EditIcon: React.FC<EditIconProps>
-  SelectIcon: React.FC<SelectIconProps>
-  strings: {
+  enableLogs: boolean // enable console logs
+  themeMode: 'light' | 'dark' // themeMode for internal components
+  primaryColor: string // primary color for internal components
+  Typography: React.FC<TypographyProps> // component used to surround text
+  Modal: React.FC<ModalProps> // modal dialog component (it displays metadata forms)
+  IconButton: React.FC<IconButtonProps> // wrapper for icon buttons
+  DeleteIcon: React.FC<DeleteIconProps> // delete icon
+  SelectIcon: React.FC<SelectIconProps> // select icon
+  CopyIcon: typeof CopyIcon // copy icon (clone a shape)
+  AnnotateIcon: typeof AnnotateIcon // annotate icon (open metadata form)
+  CloseIcon: typeof CloseIcon // close icon
+  SaveIcon: typeof SaveIcon // save icon
+  TextField: typeof TextField // field used for text input
+  NumberField: typeof NumberField // field used for number input
+  BoolField: typeof BoolField // field used for boolean input
+  EnumField: typeof EnumField // field used for enum input (options filled in parameter definition)
+  Button: typeof Button // button
+  notify: INotify // function used to display notifications
+  strings: { // strings used here and there
+    cancel: string
+    cannotDrawMorePolygons: string
+    cannotDrawMorePolylines: string
+    cannotDrawMoreRectangles: string
     id: string
+    invalidSubmission: string
+    mainParametersMetadata: string
+    missingRequiredValuesInMainParameters: string
+    missingRequiredValuesInShapeParameters: string // with {id} placeholder
+    polygon: string
+    polygonHelpText: string
+    polyline: string
+    polylineHelpText: string
+    rect: string
+    rectHelpText: string
+    pointer: string
+    pointerHelpText: string
+    requiredField: string
+    save: string
+    shapesOfTypeShouldBeEqualToThreshold: string // with {type} and {threshold} placeholders
+    shapesOfTypeShouldBeGreaterThanThreshold: string // with {type} and {threshold} placeholders
+    shapesOfTypeShouldBeGreaterThanOrEqualToThreshold: string // with {type} and {threshold} placeholders
+    shapesOfTypeShouldBeLessThanThreshold: string // with {type} and {threshold} placeholders
+    shapesOfTypeShouldBeLessThanOrEqualToThreshold: string // with {type} and {threshold} placeholders
     type: string
   }
 }
@@ -66,22 +320,59 @@ 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
+  maxWidth: '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`
+- `react-cam-roi-modal-footer`
+- `react-cam-roi-modal-footer-light`
+- `react-cam-roi-modal-footer-dark`
+
 #### Typography
 
 ##### Interface
 
-``` ts 
+```ts
 type TypographyProps = {
   children?: React.ReactNode
+  variant?: any // compatible with mui
+  component?: any // compatible with mui
+  className?: string
+  style?: React.CSSProperties
 }
 ```
 
@@ -89,18 +380,26 @@ type TypographyProps = {
 
 ##### Interface
 
-``` ts 
+```ts
 type IconButtonProps = {
   children?: React.ReactNode
+  disabled?: boolean
   onClick?: (event: React.MouseEvent) => void
 }
 ```
 
+##### Classes
+
+- `react-cam-roi-icon-button`
+- `react-cam-roi-icon-button-light`
+- `react-cam-roi-icon-button-dark`
+- `react-cam-roi-icon-button-disabled`
+
 #### DeleteIcon
 
 ##### Interface
 
-``` ts 
+```ts
 type DeleteIconProps = {
   color?: string
   style?: React.CSSProperties
@@ -111,7 +410,7 @@ type DeleteIconProps = {
 
 ##### Interface
 
-``` ts 
+```ts
 type EditIconProps = {
   color?: string
   style?: React.CSSProperties
@@ -122,13 +421,220 @@ 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
+}
+```
+#### SaveIcon
+
+##### Interface
+
+```ts
+type SaveIconProps = {
+  color?: string
+  style?: React.CSSProperties
+}
+```
+
+#### TextField
+
+##### Interface
+
+```ts
+type TextFieldProps = {
+  type?: 'text' | 'email' | 'password'
+  onChange: (value: string) => void
+  value: string
+  label: string
+  helperText?: string
+  error?: boolean
+  required?: boolean
+  readOnly?: boolean
+  disabled?: boolean
+}
+```
+
+##### Classes
+
+
+- `react-cam-roi-text-field-wrapper`
+- `react-cam-roi-text-field-wrapper-light`
+- `react-cam-roi-text-field-wrapper-dark`
+- `react-cam-roi-text-field`
+- `react-cam-roi-text-field--light`
+- `react-cam-roi-text-field--dark`
+- `react-cam-roi-text-field--error`
+- `react-cam-roi-text-field-label`
+- `react-cam-roi-text-field-label-light`
+- `react-cam-roi-text-field-label-dark`
+- `react-cam-roi-text-field-label-error`
+- `react-cam-roi-text-field-helper-text`
+- `react-cam-roi-text-field-helper-text-light`
+- `react-cam-roi-text-field-helper-text-dark`
+- `react-cam-roi-text-field-helper-text-error`
+
+#### NumberField
+
+##### Interface
+
+```ts
+type NumberFieldProps = {
+  onChange: (value: number) => void
+  value: number
+  label: string
+  helperText?: string
+  error?: boolean
+  required?: boolean
+  readOnly?: boolean
+  disabled?: boolean
+}
+```
+
+##### Classes
+
+- `react-cam-roi-number-field-wrapper`
+- `react-cam-roi-number-field-wrapper-light`
+- `react-cam-roi-number-field-wrapper-dark`
+- `react-cam-roi-number-field`
+- `react-cam-roi-number-field--light`
+- `react-cam-roi-number-field--dark`
+- `react-cam-roi-number-field--error`
+- `react-cam-roi-number-field-label`
+- `react-cam-roi-number-field-label-light`
+- `react-cam-roi-number-field-label-dark`
+- `react-cam-roi-number-field-label-error`
+- `react-cam-roi-number-field-helper-text`
+- `react-cam-roi-number-field-helper-text-light`
+- `react-cam-roi-number-field-helper-text-dark`
+- `react-cam-roi-number-field-helper-text-error`
+
+#### BoolField
+
+##### Interface
+
+```ts
+type BoolFieldProps = {
+  onChange: (value: boolean) => void
+  value: boolean
+  label: string
+  helperText?: string
+  error?: boolean
+  required?: boolean
+  readOnly?: boolean
+  disabled?: boolean
+}
+```
+
+##### Classes
+
+- `react-cam-roi-bool-field-wrapper`
+- `react-cam-roi-bool-field-wrapper-light`
+- `react-cam-roi-bool-field-wrapper-dark`
+- `react-cam-roi-bool-field`
+- `react-cam-roi-bool-field--light`
+- `react-cam-roi-bool-field--dark`
+- `react-cam-roi-bool-field--error`
+- `react-cam-roi-bool-field-label`
+- `react-cam-roi-bool-field-label-light`
+- `react-cam-roi-bool-field-label-dark`
+- `react-cam-roi-bool-field-label-error`
+- `react-cam-roi-bool-field-helper-text`
+- `react-cam-roi-bool-field-helper-text-light`
+- `react-cam-roi-bool-field-helper-text-dark`
+- `react-cam-roi-bool-field-helper-text-error`
+
+#### EnumField
+
+##### Interface
+
+```ts
+type EnumFieldProps = {
+  onChange: (value: string | number | (string | number)[]) => void
+  value: string | number | (string | number)[]
+  label: string
+  helperText?: string
+  error?: boolean
+  required?: boolean
+  multiple?: boolean
+  disabled?: boolean
+}
+```
+
+##### Classes
+
+- `react-cam-roi-enum-field-wrapper`
+- `react-cam-roi-enum-field-wrapper-light`
+- `react-cam-roi-enum-field-wrapper-dark`
+- `react-cam-roi-enum-field`
+- `react-cam-roi-enum-field--light`
+- `react-cam-roi-enum-field--dark`
+- `react-cam-roi-enum-field--error`
+- `react-cam-roi-enum-field-label`
+- `react-cam-roi-enum-field-label-light`
+- `react-cam-roi-enum-field-label-dark`
+- `react-cam-roi-enum-field-label-error`
+- `react-cam-roi-enum-field-helper-text`
+- `react-cam-roi-enum-field-helper-text-light`
+- `react-cam-roi-enum-field-helper-text-dark`
+- `react-cam-roi-enum-field-helper-text-error`
+
+
+#### Button
+
+##### Interface
+
+```ts
+type ButtonProps = {
+  onClick: (event: React.MouseEvent) => void
+  primary?: boolean
+  disabled?: boolean
+}
+```
+
+##### Classes
+
+- `react-cam-roi-button`
+- `react-cam-roi-button-light`
+- `react-cam-roi-button-dark`
+- `react-cam-roi-button-disabled`
+- `react-cam-roi-button-disabled-light`
+- `react-cam-roi-button-disabled-dark`
+
+### 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.
@@ -141,15 +647,29 @@ There are components that cannot be overridden. But still you can use classes to
 
 #### Toolbar
 
+- `react-cam-roi-toolbar-info`
+- `react-cam-roi-toolbar-info-light`
+- `react-cam-roi-toolbar-info-dark`
+
 - `react-cam-roi-toolbar`
 - `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`
+
+#### Shapes list
 
-- `react-cam-roi-metadata-table`
-- `react-cam-roi-metadata-table-light`
-- `react-cam-roi-metadata-table-dark`
+- `react-cam-roi-shapes-table`
+- `react-cam-roi-shapes-table-light`
+- `react-cam-roi-shapes-table-dark`
 
 #### Colorpicker button
 
@@ -160,3 +680,42 @@ 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`
+
+#### Form
+
+- `react-cam-roi-form`
+
+## 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
+```