@abidibo/react-cam-roi 0.0.8 → 0.0.11

package/README.md

@@ -2,47 +2,117 @@
 
 > Still in development!
 
-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.
+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 has dynamic metadata attached (configured via api).
+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 dynamic metadata information attached to each shape and the whole image.
+- 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
 
-```
+``` bash
 npm install @abidibo/react-cam-roi
 ```
 
 ## Usage
 
 ```ts
-import { RoiEditor, UiProvider } from '@abidibo/react-cam-roi'
+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 = {} // se below
+    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} />
+          <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 = {
+  // id of this editor instance, should be unique
+  id: string
+  // the url of the image we want to annotate
+  imageUrl: string
+  // configuration object
+  configuration: Configuration
+  // callback called when exporting data
+  onSubmit: (data: Output) => void
+  // initial imported data
+  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:
@@ -52,6 +122,7 @@ The configuration prop defines which kind and how many ROIs can be drawn, along
 // 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',
@@ -59,8 +130,10 @@ export const enum ToolEnum {
   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',
@@ -68,6 +141,7 @@ export enum DataTypeEnum {
   Boolean = 'bool',
 }
 
+// Operators allowed for multiplicity (control how many shapes should/can be drawn)
 export enum OperatorEnum {
   Lt = 'lt',
   Lte = 'lte',
@@ -76,32 +150,41 @@ export enum OperatorEnum {
   Eq = 'eq',
 }
 
+// Definition of a metadata parameter
 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
+  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
 }
 
+// Configuration of ROIs
 export type RoiConfiguration = {
-  role: string
-  type: Omit<ShapeType, 'pointer'>
-  multiplicity: {
+  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[]
+  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: [
     {
@@ -148,21 +231,25 @@ export const configuration: Configuration = {
       ],
     },
   ],
+  options?: {
+    hideForbiddenTools?: boolean,
+    description?: string,
+  }
 }
 ```
 
-## Customization
+## 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 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
+``` tsx
 import IconButton from '@mui/material/IconButton'
 import { UiProvider, RoiEditor } from 'react-cam-roi'
 
@@ -182,22 +269,34 @@ 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: {
+  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
@@ -206,6 +305,13 @@ type UiContextType = {
     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
   }
 }
@@ -239,7 +345,7 @@ type ModalProps = {
   title: string
   onClose: () => void
   isOpen: boolean
-  size: 'xs' | 'sm' | 'md' | 'lg'
+  maxWidth: 'xs' | 'sm' | 'md' | 'lg'
 }
 ```
 
@@ -257,6 +363,9 @@ type ModalProps = {
 - `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
 
@@ -268,6 +377,7 @@ type TypographyProps = {
   variant?: any // compatible with mui
   component?: any // compatible with mui
   className?: string
+  style?: React.CSSProperties
 }
 ```
 
@@ -278,10 +388,18 @@ type TypographyProps = {
 ```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
@@ -330,11 +448,186 @@ type CopyIconProps = {
 
 ##### Interface
 
-````ts
+```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
 
@@ -345,7 +638,7 @@ type INotify = { // compatible with toast (react-toastify)
   error: (message: string) => void
   success: (message: string) => void
 }
-````
+```
 
 ### Styles
 
@@ -359,6 +652,10 @@ 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`
@@ -389,6 +686,10 @@ There are components that cannot be overridden. But still you can use classes to
 - `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:

package/dist/Components/BoolField/BoolField.module.css

@@ -0,0 +1,60 @@
+/*
+.bool-field-wrapper {
+  margin-bottom: 2rem;
+}
+.bool-field-wrapper-light {
+}
+.bool-field-wrapper-dark {
+}
+*/
+
+.bool-field {
+  border-radius: 0.25rem;
+  box-sizing: border-box;
+  padding: 0.5rem;
+}
+.bool-field:focus-visible {
+  outline: none;
+  border: 1px solid #1976d2;
+}
+.bool-field-light {
+  background-color: #fff;
+  color: #333;
+  border: 1px solid #ccc;
+}
+.bool-field-dark {
+  background-color: #333;
+  border: 1px solid #666;
+  color: #fff;
+}
+.bool-field-error {
+  border: 1px solid #d32f2f;
+}
+.bool-field-label {
+  font-weight: bold;
+  display: block;
+  margin: 0 0 1rem 0;
+}
+/*
+.text-fiel-label-light {
+}
+.bool-field-label-dark {
+}
+*/
+.bool-field-label-error {
+  color: #d32f2f;
+}
+.bool-field-helper-text {
+  font-style: italic;
+  font-size: 0.9rem;
+  margin-top: 0.5rem;
+}
+/*
+.bool-field-helper-text-light {
+}
+.bool-field-helper-text-dark {
+}
+*/
+.bool-field-helper-text-error {
+  color: #d32f2f;
+}

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

@@ -0,0 +1,5 @@
+import { FieldProps } from "../../Types";
+declare const BoolField: React.FC<Omit<FieldProps<boolean>, 'onChange'> & {
+    onChange: (value: boolean) => void;
+}>;
+export default BoolField;

package/dist/Components/BoolField/index.js

@@ -0,0 +1,13 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from "react";
+import { UiContext } from "../../Providers/UiProvider";
+import { css } from "../../Utils";
+import styles from './BoolField.module.css';
+const BoolField = ({ onChange, value, label, helperText, error, readOnly = false, disabled = false, required = false, }) => {
+    const { themeMode, Typography } = useContext(UiContext);
+    const handleChange = (e) => {
+        onChange(e.target.checked);
+    };
+    return (_jsxs("div", { className: css('bool-field-wrapper', styles, themeMode), children: [_jsx("label", { className: `${css('bool-field-label', styles, themeMode)} ${error ? css('bool-field-label-error', styles, null) : ''}`, children: _jsxs(Typography, { children: [label, required && ' *'] }) }), _jsx("input", { type: 'checkbox', className: `${css('bool-field', styles, themeMode)} ${error ? css('bool-field-error', styles, null) : ''}`, onChange: handleChange, checked: value, readOnly: readOnly, disabled: disabled }), helperText && (_jsx(Typography, { component: 'div', className: `${css('bool-field-helper-text', styles, themeMode)} ${error ? css('bool-field-helper-text-error', styles, null) : ''}`, children: helperText }))] }));
+};
+export default BoolField;

package/dist/Components/Button/Button.module.css

@@ -0,0 +1,27 @@
+.button {
+  border: none;
+  border-radius: 4px;
+  color: black;
+  padding: .5rem 1rem;
+  text-align: center;
+  text-decoration: none;
+  display: inline-block;
+  font-size: 16px;
+  margin: 4px 2px;
+  cursor: pointer;
+}
+
+.button-light {
+  background-color: #d7d7d7;
+  color: black;
+}
+
+.button-dark {
+  background-color: #383838;
+  color: white;
+}
+
+.button-disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}

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

@@ -0,0 +1,8 @@
+import { PropsWithChildren } from 'react';
+export type ButtonProps = {
+    onClick: (event: React.MouseEvent) => void;
+    primary?: boolean;
+    disabled?: boolean;
+};
+declare const Button: ({ onClick, primary, disabled, children }: PropsWithChildren<ButtonProps>) => import("react/jsx-runtime").JSX.Element;
+export default Button;

package/dist/Components/Button/index.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from 'react';
+import { UiContext } from '../../Providers/UiProvider';
+import { css } from '../../Utils';
+import styles from './Button.module.css';
+const Button = ({ onClick, primary, disabled, children }) => {
+    const { themeMode, primaryColor } = useContext(UiContext);
+    const style = {};
+    if (primary) {
+        style.backgroundColor = primaryColor;
+        style.color = 'white';
+    }
+    return (_jsx("button", { className: `${css('button', styles, themeMode)}${disabled ? ` ${css('button-disabled', styles, themeMode)}` : ''}`, style: style, onClick: onClick, disabled: disabled, children: children }));
+};
+export default Button;