Add file size limits, mimetype validation, and MobileNet model version support

README.md

@@ -8,7 +8,10 @@ This package uses TensorFlow.js and the pre-trained MobileNet model to recognize
 ## Features
 
 -   Processes images from a local file path.
--   Uses the popular and efficient MobileNet model.
+-   Uses the popular and efficient MobileNet model (versions 1 and 2 supported).
+-   File size limit control to prevent processing of oversized images.
+-   Mimetype validation to ensure only supported image formats are processed.
+-   Supports JPEG, PNG, BMP, WebP, and TIFF formats (excludes GIF, SVG, and other unsupported formats).
 -   Written in TypeScript and includes type definitions.
 -   Provides an easy-to-use and flexible API.
 
@@ -28,7 +31,9 @@ yarn add image2tags
 
 ## Usage
 
-After importing the package into your project, you can use the `getImageTags` function. This function takes the file path of an image as a parameter and returns a `Promise`. This `Promise` resolves with an array containing the tags and their probabilities.
+After importing the package into your project, you can use the `getImageTags` function. This function takes the file path of an image and optional configuration options, and returns a `Promise` that resolves with an array containing the tags and their probabilities.
+
+### Basic Usage
 
 ```typescript
 import { getImageTags } from 'image2tags';
@@ -51,6 +56,37 @@ async function main() {
 main();
 ```
 
+### Advanced Usage with Options
+
+```typescript
+import { getImageTags, ImageTagOptions } from 'image2tags';
+import * as path from 'path';
+
+async function main() {
+  try {
+    const imagePath = path.join(__dirname, 'path/to/your/image.jpg');
+
+    // Configure options
+    const options: ImageTagOptions = {
+      topK: 5,                    // Return top 5 predictions
+      maxFileSize: 5242880,       // Max 5MB file size
+      modelVersion: 2             // Use MobileNet v2 (default)
+    };
+
+    const tags = await getImageTags(imagePath, options);
+
+    console.log('Detected Tags:');
+    tags.forEach(tag => {
+      console.log(`- ${tag.className} (Probability: ${(tag.probability * 100).toFixed(2)}%)`);
+    });
+  } catch (error) {
+    console.error('An error occurred while getting tags:', error);
+  }
+}
+
+main();
+```
+
 ### CLI Usage
 
 You can also use this package as a command-line tool.
@@ -63,14 +99,26 @@ image2tags <path/to/your/image.jpg>
 
 - `-k, --topK <number>`: Specify the number of top predictions to return (default: 10).
 - `--json`: Output results in JSON format.
+- `--max-size <bytes>`: Maximum file size in bytes (e.g., 5242880 for 5MB).
+- `--model <version>`: MobileNet model version (1 or 2, default: 2).
 
-**Example:**
+**Examples:**
 
 ```bash
+# Basic usage
 image2tags tests/fixtures/sample.jpg -k 5
+
+# With file size limit (5MB)
+image2tags tests/fixtures/sample.jpg --max-size 5242880
+
+# Using MobileNet v1
+image2tags tests/fixtures/sample.jpg --model 1
+
+# JSON output with all options
+image2tags tests/fixtures/sample.jpg -k 3 --max-size 10485760 --model 2 --json
 ```
 
-**Example with JSON output:**
+**Example JSON output:**
 
 ```bash
 image2tags tests/fixtures/sample.jpg --json
@@ -98,10 +146,66 @@ Which will produce the following output:
 ]
 ```
 
-### Parameters
+### API Reference
+
+#### `getImageTags(imagePath: string, options?: ImageTagOptions | number): Promise<Tag[]>`
+
+**Parameters:**
 
 -   `imagePath` (string, required): The file path of the image to be processed.
--   `topK` (number, optional, default: 10): The number of top predictions to return.
+-   `options` (ImageTagOptions | number, optional): Configuration options or a number for backward compatibility.
+    -   If a number is provided, it's treated as `topK` (for backward compatibility).
+    -   If an object is provided, it can include:
+        -   `topK` (number, optional, default: 10): The number of top predictions to return.
+        -   `maxFileSize` (number, optional): Maximum file size in bytes. Files exceeding this size will throw an error.
+        -   `modelVersion` (1 | 2, optional, default: 2): MobileNet model version to use.
+
+**Returns:**
+
+-   `Promise<Tag[]>`: A promise that resolves to an array of tag objects.
+
+**Tag Object:**
+
+```typescript
+interface Tag {
+  className: string;      // Full classification name (may include multiple synonyms)
+  tags: string[];         // Array of individual tag strings
+  probability: number;    // Confidence score (0-1)
+}
+```
+
+### Supported Image Formats
+
+The package supports the following image formats:
+- JPEG (`.jpg`, `.jpeg`)
+- PNG (`.png`)
+- BMP (`.bmp`)
+- WebP (`.webp`)
+- TIFF (`.tif`, `.tiff`)
+
+**Note:** GIF, SVG, and other formats are **not supported** as they cannot be processed by TensorFlow.js image classification models.
+
+### Error Handling
+
+The package will throw errors in the following cases:
+- File size exceeds the `maxFileSize` limit (if specified)
+- Unsupported file format (e.g., GIF, SVG)
+- Invalid or corrupted image file
+- File not found
+
+```typescript
+try {
+  const tags = await getImageTags(imagePath, { maxFileSize: 1048576 }); // 1MB limit
+} catch (error) {
+  if (error.message.includes('exceeds the maximum allowed size')) {
+    console.error('File is too large');
+  } else if (error.message.includes('Unsupported file type')) {
+    console.error('Invalid image format');
+  } else {
+    console.error('Error processing image:', error);
+  }
+}
+```
 
 ## Running Tests