@umituz/react-native-ai-generation-content 1.17.232 → 1.17.233

package/src/features/remove-background/README.md

@@ -1,292 +1,393 @@
-# Remove Background
+# Remove Background Feature
 
 Remove backgrounds from images using AI with precision.
 
-## Features
+## 📍 Import Path
 
-- Automatic background detection and removal
-- Keep main subject while removing background
-- Support for complex subjects (hair, fur, transparent objects)
-- Fine-tune edges for professional results
-- Export as transparent PNG
+```typescript
+import { useRemoveBackgroundFeature } from '@umituz/react-native-ai-generation-content';
+```
 
-## Installation
+**Location**: `src/features/remove-background/`
 
-This feature is part of `@umituz/react-native-ai-generation-content`.
+## 🎯 Feature Purpose
 
-```bash
-npm install @umituz/react-native-ai-generation-content
-```
+Automatically detect and remove backgrounds from images using AI. Keeps main subjects while removing backgrounds, handling complex edges like hair, fur, and transparent objects.
 
-## Basic Usage
+---
 
-### Using the Hook
+## 📋 Usage Strategy
 
-```tsx
-import { useRemoveBackgroundFeature } from '@umituz/react-native-ai-generation-content';
-import * as ImagePicker from 'react-native-image-picker';
-
-function RemoveBackgroundScreen() {
-  const [image, setImage] = useState<string | null>(null);
-
-  const feature = useRemoveBackgroundFeature({
-    config: {
-      edgeSmoothness: 'medium',
-      onProcessingStart: () => console.log('Removing background...'),
-      onProcessingComplete: (result) => console.log('Complete:', result),
-      onError: (error) => console.error('Error:', error),
-    },
-    onSelectImage: async () => {
-      const result = await ImagePicker.launchImageLibrary({ mediaType: 'photo' });
-      if (result.assets && result.assets[0].uri) {
-        const base64 = await convertToBase64(result.assets[0].uri);
-        setImage(base64);
-        return base64;
-      }
-      return null;
-    },
-    onSaveImage: async (imageUrl) => {
-      await saveToGallery(imageUrl);
-    },
-  });
-
-  return (
-    <View>
-      <PhotoUploadCard
-        image={image}
-        onSelectImage={feature.selectImage}
-        title="Select Image to Remove Background"
-      />
-
-      <Button
-        title="Remove Background"
-        onPress={feature.process}
-        disabled={!feature.isReady || feature.state.isProcessing}
-      />
-
-      {feature.state.isProcessing && (
-        <ActivityIndicator />
-      )}
-
-      {feature.state.result && (
-        <ResultDisplay
-          originalImage={image}
-          resultImage={feature.state.result.imageUrl}
-          onSave={() => feature.saveResult()}
-          showTransparentBackground
-        />
-      )}
-    </View>
-  );
-}
-```
+### When to Use This Feature
 
-### Using the Unified AI Feature Screen
+✅ **Use Cases:**
+- Product photography for e-commerce
+- Creating transparent images for design
+- Profile picture background removal
+- Preparing images for marketing materials
+- Isolating subjects for compositing
+- Creating stickers and overlays
 
-```tsx
-import { AIFeatureScreen } from '@umituz/react-native-ai-generation-content';
+❌ **When NOT to Use:**
+- Manual background selection (use image editing software)
+- Background replacement (use Replace Background)
+- Object removal from photos (use Remove Object)
+- Photo restoration (use Photo Restoration)
 
-function App() {
-  return (
-    <AIFeatureScreen
-      featureId="remove-background"
-      userId="user-123"
-    />
-  );
-}
-```
+### Implementation Strategy
 
-## Configuration Options
+1. **Upload image** with clear subject
+2. **Preview detection** before processing
+3. **Choose edge smoothness** level
+4. **Show before/after comparison** with transparency
+5. **Provide download** as transparent PNG
+6. **Offer fine-tuning** options for edges
 
-### Feature Config
+---
 
-```tsx
-interface RemoveBackgroundFeatureConfig {
-  edgeSmoothness?: 'low' | 'medium' | 'high';
-  returnMask?: boolean; // Return the mask along with result
-  onProcessingStart?: () => void;
-  onProcessingComplete?: (result: RemoveBackgroundResult) => void;
-  onError?: (error: string) => void;
-}
-```
+## ⚠️ Critical Rules (MUST FOLLOW)
 
-### Processing Options
+### 1. Image Requirements
+- **MUST** provide ONE image to process
+- **MUST** have clear subject in image
+- **MUST** use reasonable resolution (min 512x512)
+- **MUST** use supported formats (JPEG, PNG)
+- **MUST NOT** exceed file size limits (10MB max)
 
-```tsx
-interface RemoveBackgroundOptions {
-  edgeSmoothness: 'low' | 'medium' | 'high';
-  featherEdges?: boolean; // Soften edges for natural look
-  preserveHair?: boolean; // Better hair detection (default: true)
-  backgroundColor?: string; // Add new background color
-}
+### 2. Configuration
+- **MUST** provide valid `userId` for tracking
+- **MUST** specify `edgeSmoothness` (low, medium, high)
+- **MUST** implement `onError` callback
+- **MUST** implement `onSelectImage` callback
+- **MUST** handle transparent PNG output
+
+### 3. State Management
+- **MUST** check `isReady` before enabling remove button
+- **MUST** display progress during processing
+- **MUST** handle transparency display properly
+- **MUST** display `error` state with clear messages
+- **MUST** implement proper cleanup on unmount
+
+### 4. Performance
+- **MUST** implement image compression before upload
+- **MUST** show progress indicator for processing
+- **MUST** cache results locally
+- **MUST** handle large output images
+- **MUST NOT** process multiple images simultaneously
+
+### 5. User Experience
+- **MUST** show background preview with transparency grid
+- **MUST** provide before/after comparison
+- **MUST** offer edge smoothness options
+- **MUST** handle complex subjects (hair, fur)
+- **MUST** provide download as PNG
+
+---
+
+## 🚫 Prohibitions (MUST AVOID)
+
+### Strictly Forbidden
+
+❌ **NEVER** do the following:
+
+1. **No Missing Images**
+   - Always validate image is selected
+   - Never call process() without image
+
+2. **No Auto-Processing**
+   - Never start removal without user action
+   - Always require explicit "Remove Background" button press
+   - Provide clear preview before processing
+
+3. **No Hardcoded Credentials**
+   - Never store API keys in component files
+   - Use environment variables or secure storage
+
+4. **No Unhandled Errors**
+   - Never ignore detection failures
+   - Always explain what went wrong
+   - Provide retry or alternative options
+
+5. **No Memory Leaks**
+   - Never store large images unnecessarily
+   - Clean up temporary images
+   - Implement proper image disposal
+
+6. **No Blocking UI**
+   - Never block main thread with image processing
+   - Always show progress indicator
+   - Allow cancellation
+
+7. **No Poor Quality Output**
+   - Never compress PNG output excessively
+   - Preserve transparency quality
+   - Use appropriate edge settings
+
+---
+
+## 🤖 AI Agent Directions
+
+### For AI Code Generation Tools
+
+When using this feature with AI code generation tools, follow these guidelines:
+
+#### Prompt Template for AI Agents
+
+```
+You are implementing a background removal feature using @umituz/react-native-ai-generation-content.
+
+REQUIREMENTS:
+1. Import from: @umituz/react-native-ai-generation-content
+2. Use the useRemoveBackgroundFeature hook
+3. Select edge smoothness level
+4. Implement image selection UI
+5. Validate image before processing
+6. Show before/after comparison with transparency
+7. Display result on transparency grid
+8. Implement proper error handling
+9. Provide PNG download
+10. Implement cleanup on unmount
+
+CRITICAL RULES:
+- MUST validate image before calling remove()
+- MUST show before/after comparison
+- MUST display transparency grid properly
+- MUST handle complex subjects (hair, fur)
+- MUST implement debouncing (300ms)
+- MUST provide PNG format output
+
+CONFIGURATION:
+- Provide valid userId (string)
+- Set edgeSmoothness: 'low' | 'medium' | 'high'
+- Implement onSelectImage callback
+- Implement onSaveImage callback
+- Configure callbacks: onProcessingStart, onProcessingComplete, onError
+
+OPTIONS:
+- edgeSmoothness: 'low' | 'medium' | 'high'
+  - Low: Sharper edges, better for objects
+  - Medium: Balanced (recommended)
+  - High: Smoother edges, better for hair/fur
+
+STRICTLY FORBIDDEN:
+- No missing image validation
+- No auto-processing without user action
+- No hardcoded API keys
+- No unhandled errors
+- No memory leaks
+- No blocking UI
+- No poor quality PNG output
+
+QUALITY CHECKLIST:
+- [ ] Image selection implemented
+- [ ] Edge smoothness selector
+- [ ] Transparency grid display
+- [ ] Before/after comparison view
+- [ ] Progress indicator during processing
+- [ ] Error display with retry option
+- [ ] PNG download functionality
+- [ ] Original image preserved
 ```
 
-## Usage Flow
+#### AI Implementation Checklist
 
-1. Select **Image** - Choose an image with background to remove
-2. Configure **Options** - Adjust edge smoothness and other settings
-3. Tap **Remove Background** - Start the removal process
-4. View **Result** - See the image with transparent background
-5. Save or Edit - Save as PNG or add new background
+Use this checklist when generating code:
 
-## Component Examples
+- [ ] Feature imported from correct path
+- [ ] Image selection implemented
+- [ ] Edge smoothness selector added
+- [ ] Validation before remove()
+- [ ] Transparency grid for result display
+- [ ] Before/after comparison view
+- [ ] Progress indicator during processing
+- [ ] Error display with user-friendly message
+- [ ] PNG download with transparency
+- [ ] Cleanup on unmount
+- [ ] Original image preserved
+- [ ] Complex subject handling
 
-### Edge Smoothness Selector
+---
 
-```tsx
-import { GridSelector } from '@umituz/react-native-ai-generation-content';
+## 🛠️ Configuration Strategy
 
-const smoothnessOptions = [
-  { id: 'low', name: 'Sharp', description: 'Precise edges' },
-  { id: 'medium', name: 'Balanced', description: 'Natural edges' },
-  { id: 'high', name: 'Smooth', description: 'Soft edges' },
-];
+### Essential Configuration
 
-function MyScreen() {
-  const [smoothness, setSmoothness] = useState('medium');
+```typescript
+// Required fields
+{
+  userId: string
+  edgeSmoothness: 'low' | 'medium' | 'high'
+  onSelectImage: () => Promise<string | null>
+}
 
-  return (
-    <GridSelector
-      options={smoothnessOptions}
-      selectedOption={smoothness}
-      onSelectOption={setSmoothness}
-    />
-  );
+// Optional callbacks
+{
+  onProcessingStart?: () => void
+  onProcessingComplete?: (result) => void
+  onError?: (error: string) => void
 }
 ```
 
-### Background Preview
-
-```tsx
-import { View, Image } from 'react-native';
-
-const previewBackgrounds = [
-  { color: '#FFFFFF', name: 'White' },
-  { color: '#000000', name: 'Black' },
-  { color: '#F0F0F0', name: 'Gray' },
-  { color: 'transparent', name: 'Transparent' },
-];
-
-function BackgroundPreview({ imageUrl }) {
-  const [background, setBackground] = useState('transparent');
-
-  return (
-    <View style={{ backgroundColor: background }}>
-      <Image
-        source={{ uri: imageUrl }}
-        style={{ width: 300, height: 300 }}
-      />
-    </View>
-  );
+### Recommended Settings
+
+1. **Edge Smoothness**
+   - Low: Sharp edges, best for simple objects
+   - Medium: Balanced (recommended for most cases)
+   - High: Smooth edges, best for hair, fur, complex subjects
+
+2. **Image Quality**
+   - Minimum: 512x512 resolution
+   - Recommended: 1024x1024 or higher
+   - Format: JPEG or PNG
+   - Max size: 10MB
+
+3. **Performance Settings**
+   - Compress images before upload
+   - Show progress for operations
+   - Implement timeout (60s default)
+   - Enable result caching
+
+---
+
+## 📊 State Management
+
+### Feature States
+
+**isReady**: boolean
+- Image selected and validated
+- Check before enabling remove button
+
+**isProcessing**: boolean
+- Background removal in progress
+- Show loading/progress indicator
+- Disable remove button
+
+**progress**: number (0-100)
+- Processing progress percentage
+- Update progress bar
+
+**error**: string | null
+- Error message if processing failed
+- Display to user with clear message
+
+**result**: {
+  imageUrl: string  // Transparent PNG
+  originalImageUrl?: string
+  edgeSmoothness?: string
+  metadata?: any
 }
-```
 
-### Before/After Comparison
+---
 
-```tsx
-import { ResultDisplay } from '@umituz/react-native-ai-generation-content';
+## 🎨 Best Practices
 
-{feature.state.result && image && (
-  <ResultDisplay
-    originalImage={image}
-    resultImage={feature.state.result.imageUrl}
-    onSave={() => feature.saveResult()}
-    onShare={() => shareImage(feature.state.result.imageUrl)}
-  />
-)}
-```
+### Image Selection
 
-## Advanced Usage
+1. **Subject Clarity**
+   - Good: Clear separation between subject and background
+   - Bad: Similar colors, low contrast between subject and background
 
-### Custom Edge Smoothness
+2. **Lighting**
+   - Good: Even lighting on subject
+   - Bad: Harsh shadows, complex backgrounds
 
-```tsx
-const result = await feature.process({
-  edgeSmoothness: 'high',
-  featherEdges: true,
-  preserveHair: true,
-});
-```
+3. **Edge Complexity**
+   - Simple objects: Use low edge smoothness
+   - Hair/fur: Use high edge smoothness
+   - Mixed: Use medium edge smoothness
 
-### Add New Background
+### User Experience
 
-```tsx
-// After removing background, add a new one
-const result = await feature.process({
-  edgeSmoothness: 'medium',
-  backgroundColor: '#FF5733', // Orange background
-});
-```
+1. **Transparency Display**
+   - Show checkerboard pattern for transparency
+   - Allow background color preview
+   - Provide zoom for edge inspection
 
-### Export with Mask
+2. **Comparison Tools**
+   - Before/after slider
+   - Toggle original/removed
+   - Edge detail zoom
 
-```tsx
-const result = await feature.process({
-  edgeSmoothness: 'medium',
-  returnMask: true,
-});
+3. **Output Quality**
+   - Always provide PNG format
+   - Preserve edge quality
+   - Offer multiple resolution options
 
-// result.maskUrl contains the segmentation mask
-```
+---
 
-## Use Cases
+## 🐛 Common Pitfalls
 
-### Product Photos
+### Detection Issues
 
-```tsx
-// Remove background for e-commerce product photos
-const result = await feature.process({
-  edgeSmoothness: 'high',
-  preserveHair: false,
-});
-```
+❌ **Problem**: Background not fully removed
+✅ **Solution**: Ensure good subject-background contrast, try different edge smoothness
 
-### Profile Pictures
+### Edge Quality Issues
 
-```tsx
-// Create clean profile pictures
-const result = await feature.process({
-  edgeSmoothness: 'medium',
-  featherEdges: true,
-});
-```
+❌ **Problem**: Jagged or unnatural edges
+✅ **Solution**: Adjust edge smoothness, use higher setting for hair/fur
 
-### Graphic Design
+### Transparency Issues
 
-```tsx
-// Extract subjects for design work
-const result = await feature.process({
-  edgeSmoothness: 'low',
-  returnMask: true,
-});
-```
+❌ **Problem**: Transparency not visible
+✅ **Solution**: Display with checkerboard pattern, offer background preview
 
-## Best Practices
+### Performance Issues
 
-1. **Image Quality**: Use high-resolution images for best results
-2. **Subject Separation**: Ensure subject is clearly separated from background
-3. **Edge Smoothness**: Adjust based on subject type (high for hair, low for objects)
-4. **Hair/Fur**: Enable hair preservation for better results
-5. **Lighting**: Even lighting produces better edge detection
+❌ **Problem**: Slow processing
+✅ **Solution**: Compress images, show progress, implement timeout
 
-## Error Handling
+---
 
-```tsx
-const { state, process } = useRemoveBackgroundFeature({ ...config });
+## 📦 Related Components
 
-useEffect(() => {
-  if (state.error) {
-    Alert.alert('Removal Failed', state.error);
-  }
-}, [state.error]);
-```
+Use these components from the library:
+
+- **PhotoUploadCard**: Upload image interface
+- **ResultDisplay**: Before/after comparison
+- **TransparencyGrid**: Display transparent images
+- **EdgeSmoothnessSelector**: Choose edge quality
+- **ProgressBar**: Progress display
+
+Located at: `src/presentation/components/`
+
+---
+
+## 🔄 Migration Strategy
+
+If migrating from previous implementation:
+
+1. **Update imports** to new path
+2. **Add edge smoothness selector**
+3. **Implement transparency grid display**
+4. **Update state handling** for new structure
+5. **Add before/after comparison**
+6. **Test with complex subjects**
+
+---
+
+## 📚 Additional Resources
+
+- Main documentation: `/docs/`
+- API reference: `/docs/api/`
+- Examples: `/docs/examples/basic/remove-background/`
+- Architecture: `/ARCHITECTURE.md`
+
+---
+
+**Last Updated**: 2025-01-08
+**Version**: 2.0.0 (Strategy-based Documentation)
 
-## Related Features
+---
 
-- [Replace Background](../replace-background) - Replace with new background
-- [Remove Object](../remove-object) - Remove unwanted objects
-- [Image to Image](../image-to-image) - Transform images with AI
+## 📝 Changelog
 
-## License
+### v2.0.0 - 2025-01-08
+- **BREAKING**: Documentation format changed to strategy-based
+- Removed extensive code examples
+- Added rules, prohibitions, and AI agent directions
+- Focus on best practices and implementation guidance
+- Added transparency handling guidelines
 
-MIT
+### v1.0.0 - Initial Release
+- Initial feature documentation