Skip to content

usage.md

Latest commit

 

History

History
793 lines (600 loc) · 23.6 KB

usage.md

File metadata and controls

793 lines (600 loc) · 23.6 KB

🎮 Usage Guide

📋 Overview

This comprehensive usage guide provides step-by-step instructions, examples, and best practices for using VisoLearn-2 effectively. It covers all major features, modules, and workflows.

🚀 Getting Started

First-Time Setup

  1. Launch the Application

    python app.py

  2. Access the Interface

  3. User Profile Setup

    • Click on "Settings" or "User Profile"
    • Enter basic information (name, age, autism level)
    • Select preferences (image style, difficulty level)
    • Save your profile

Interface Navigation

Main Sections:

  • 🖼️ Image Description Practice: Develop visual analysis skills
  • 📖 Comic Story Generator: Enhance narrative comprehension
  • 📊 Analytics Dashboard: Track progress and achievements
  • ⚙️ Settings: Configure application preferences

🖼️ Image Description Practice Module

Starting a New Session

  1. Select Module: Click on "Image Description Practice"
  2. Choose Parameters:
    • Age: Select appropriate age range
    • Autism Level: Choose support level (1-3)
    • Topic: Select interest area (animals, objects, people, etc.)
    • Difficulty: Start with "Simple" for beginners
  3. Start Session: Click "Begin Practice"

Image Generation Process

Example Workflow:

# Behind the scenes, this is what happens:
from models.image_generation import generate_image_fn
from models.prompt_generation import generate_contextual_prompt

# Generate appropriate prompt
prompt = generate_contextual_prompt(
    age=8,
    autism_level=2,
    topic="animals",
    difficulty=1
)

# Generate image
image = generate_image_fn(prompt)

Describing the Image

Step-by-Step Guide:

  1. Observe the Image: Take time to look at all details
  2. Identify Key Elements:
    • Main objects
    • Colors
    • Positions
    • Actions
    • Background elements
  3. Formulate Description:
    • Start with the main subject
    • Add details progressively
    • Use simple, clear language
  4. Submit Description: Click "Submit" or press Enter

Example Descriptions:

Beginner Level:

  • "I see a cat"
  • "There is a dog"
  • "A boy with a ball"

Intermediate Level:

  • "I see a brown cat sitting on a blue mat"
  • "There is a happy boy playing with a red ball in the park"
  • "A yellow bird is flying near a green tree"

Advanced Level:

  • "I see a large brown cat with white paws sitting comfortably on a blue rectangular mat in a sunny room with a window showing trees outside"
  • "There is a cheerful boy wearing a blue shirt and red shorts playing with a bright red ball in a grassy park with tall green trees and a blue sky with white clouds"

Receiving Feedback

Feedback Components:

  • ✅ Accuracy Score: Percentage of correct details
  • 📝 Correct Details: Elements you identified correctly
  • ❌ Missed Details: Important elements you didn't mention
  • 💡 Constructive Feedback: Encouraging suggestions for improvement

Example Feedback:

{
  "score": 85,
  "feedback": "Great job! You identified the main subject and colors very well. Try adding more details about the background and what the cat is doing.",
  "missing_details": ["blue mat", "sunny room", "window"],
  "correct_details": ["brown cat", "white paws", "sitting"]
}

Progressing Through Difficulty Levels

Level Progression:

  • Very Simple: Basic objects, minimal details
  • Simple: Clear objects with basic details
  • Moderate: Multiple elements with relationships
  • Detailed: Complex scenes with many details
  • Very Detailed: Rich, educational content

Automatic Advancement:

  • Complete 3-5 successful descriptions at current level
  • Achieve average score of 70%+ on current level
  • System automatically suggests level increase

📖 Comic Story Generator Module

Creating a New Story

  1. Select Module: Click on "Comic Story Generator"
  2. Choose Story Parameters:
    • Topic: Educational focus (friendship, problem-solving, etc.)
    • Characters: Select or create characters
    • Setting: Choose location (classroom, park, home, etc.)
    • Number of Panels: Start with 4 for beginners
    • Difficulty: Begin with "Simple"
  3. Generate Story: Click "Create Story"

Story Generation Process

Example Story Creation:

from models.story_generation import generate_story_prompt

story_data = generate_story_prompt(
    characters=["boy with autism", "supportive teacher"],
    setting="classroom",
    theme="overcoming challenges",
    num_panels=4
)

Analyzing the Story

Step-by-Step Analysis:

  1. Panel-by-Panel Review:

    • Examine each panel carefully
    • Note characters, actions, and setting
    • Observe relationships between panels

  2. Comprehension Questions:

    • What is happening in this panel?
    • How does this relate to the previous panel?
    • What might happen next?

  3. Story Summary:

    • Write a brief summary of the entire story
    • Identify the main theme or lesson
    • Describe character development

Example Analysis:

Panel 1:

  • "A boy named Alex is sitting at his desk in a classroom"
  • "He looks worried about his math worksheet"
  • "The teacher is smiling and approaching him"

Panel 2:

  • "The teacher is showing Alex a different way to solve the problem"
  • "She's using colorful blocks to explain the math concept"
  • "Alex is starting to look more interested"

Panel 3:

  • "Alex is trying the new method with the blocks"
  • "He's smiling and looks more confident"
  • "The teacher is watching and encouraging him"

Panel 4:

  • "Alex has solved the problem successfully"
  • "He's showing his completed worksheet to the teacher"
  • "Both are smiling and look happy"

Story Summary: "This story shows how a supportive teacher helps Alex overcome his challenge with math by using a different teaching method. The theme is about finding alternative solutions and the importance of encouragement."

Interactive Story Activities

Available Activities:

  • ✅ Panel Description: Describe each panel individually
  • 🔍 Story Sequence: Put panels in correct order
  • 💬 Character Analysis: Describe character emotions and development
  • 🎯 Theme Identification: Identify the main lesson or theme
  • 📝 Alternative Ending: Create your own ending for the story

📊 Analytics Dashboard

Understanding Your Progress

Dashboard Sections:

  1. Overall Progress:

    • Total sessions completed
    • Average accuracy score
    • Current difficulty level
    • Time spent learning

  2. Skill Development:

    • Visual analysis skills
    • Descriptive language
    • Narrative comprehension
    • Detail identification

  3. Recent Activity:

    • Last 5 sessions
    • Performance trends
    • Time spent per session

  4. Achievements:

    • Badges earned
    • Milestones reached
    • Special accomplishments

Reading Progress Charts

Chart Types:

  • Line Charts: Show progress over time
  • Bar Charts: Compare different skills
  • Pie Charts: Show time distribution
  • Heatmaps: Visualize skill development

Example Interpretation:

  • 📈 Upward trend: Your skills are improving
  • 🔄 Plateau: You may need to try different activities
  • 📉 Downward trend: Consider reducing difficulty temporarily

Exporting Progress Data

Export Options:

  • 📄 PDF Reports: Printable progress summaries
  • 📊 CSV Data: Raw data for analysis
  • 🖼️ Image Charts: Visual representations
  • 📁 Complete Archive: All session data

Export Example:

# Export progress data
python export_progress.py --user alex --format pdf --output progress_report.pdf

⚙️ Settings and Configuration

User Profile Management

Profile Settings:

  • Basic Information: Name, age, autism level
  • Learning Preferences: Preferred topics, image styles
  • Difficulty Settings: Automatic or manual progression
  • Accessibility Options: High contrast, larger text

Example Profile:

{
  "name": "Alex",
  "age": 8,
  "autism_level": 2,
  "preferences": {
    "favorite_topics": ["animals", "space", "vehicles"],
    "image_style": "cartoon",
    "difficulty_progression": "automatic",
    "theme": "light"
  }
}

Application Settings

Configurable Options:

  • Session Timeout: Automatic session saving
  • Data Backup: Frequency and location
  • Cloud Sync: Google Drive integration
  • Notifications: Progress alerts and reminders

Accessibility Features

Available Options:

  • 👁️ High Contrast Mode: Better visibility
  • 🔊 Text-to-Speech: Audio feedback
  • 📱 Touch-Friendly: Larger buttons
  • ⏱️ Extended Time: More time for responses
  • 🔄 Simplified Interface: Reduced clutter

🎯 Advanced Usage

Custom Session Creation

Creating Custom Sessions:

from models.image_generation import generate_image_fn
from utils.state_management import create_custom_session

# Define custom parameters
custom_params = {
    "age": 10,
    "autism_level": 3,
    "topic": "space exploration",
    "difficulty": "moderate",
    "image_style": "realistic",
    "specific_objects": ["rocket", "astronaut", "planet"]
}

# Create custom session
session_id = create_custom_session(custom_params)

# Generate custom image
prompt = f"{custom_params['topic']} with {', '.join(custom_params['specific_objects'])} in {custom_params['image_style']} style"
image = generate_image_fn(prompt)

Multi-User Management

Managing Multiple Users:

from utils.file_operations import load_user_profiles, switch_user

# Load available profiles
profiles = load_user_profiles()

# Switch to specific user
current_user = switch_user("alex_profile")

# User-specific data management
user_data = {
    "sessions": [],
    "progress": {
        "image_description": {"level": 2, "score": 85},
        "story_comprehension": {"level": 1, "score": 78}
    },
    "preferences": {}
}

Advanced Analytics

Custom Analytics Queries:

from utils.visualization import generate_custom_chart

# Generate custom progress analysis
analysis_params = {
    "user_id": "alex",
    "time_range": "last_30_days",
    "metrics": ["accuracy", "session_duration", "skill_development"],
    "chart_type": "line",
    "group_by": "week"
}

chart = generate_custom_chart(analysis_params)
chart.save("custom_analysis.png")

🤝 Collaborative Features

Teacher/Parent Dashboard

Dashboard Features:

  • 📊 Multi-User Overview: View all students' progress
  • 📈 Class Analytics: Group performance metrics
  • 📚 Lesson Planning: Create customized learning plans
  • 💬 Communication: Send encouraging messages
  • 📅 Scheduling: Set learning goals and reminders

Session Sharing

Sharing Options:

  • 🔗 Shareable Links: Generate links to specific sessions
  • 📧 Email Reports: Send progress reports to parents/teachers
  • ☁️ Cloud Backup: Automatic Google Drive synchronization
  • 📁 Export Packages: Complete session archives

Example Sharing:

from utils.file_operations import generate_shareable_link

# Generate shareable link for a session
share_link = generate_shareable_link(
    session_id="20240115_alex",
    access_level="view_only",
    expiry_days=7
)

print(f"Share this link: {share_link}")

📚 Learning Strategies

Effective Practice Techniques

Recommended Approaches:

  1. Short, Frequent Sessions: 15-20 minutes daily
  2. Varied Topics: Rotate between different interest areas
  3. Progressive Difficulty: Let the system guide level advancement
  4. Positive Reinforcement: Celebrate small achievements
  5. Multi-Sensory Learning: Combine visual with audio feedback

Overcoming Challenges

Common Challenges and Solutions:

Challenge Solution
Difficulty focusing Use shorter sessions, high-contrast mode
Frustration with mistakes Enable encouraging feedback mode
Limited vocabulary Start with very simple level, use image hints
Sensory overload Reduce visual clutter, simplify interface
Motivation issues Use favorite topics, set small achievable goals

Parent/Teacher Tips

Support Strategies:

  • Model the Behavior: Describe images together initially
  • Use Real-World Connections: Relate to familiar objects/experiences
  • Celebrate Progress: Focus on improvement, not perfection
  • Follow Interests: Use topics the child is passionate about
  • Be Patient: Allow time for processing and responding

🎮 Gamification Features

Achievement System

Achievement Types:

  • 🏆 First Session: Complete your first learning session
  • 🌟 Perfect Score: Achieve 100% accuracy
  • 📚 Story Master: Complete 5 story analyses
  • 🎨 Artist Eye: Identify all details in 3 consecutive images
  • 🚀 Level Up: Advance to a higher difficulty level

Progress Badges

Badge Levels:

  • 🥉 Bronze: Beginner achievements
  • 🥈 Silver: Intermediate milestones
  • 🥇 Gold: Advanced accomplishments
  • 💎 Diamond: Mastery level achievements

Reward System

Reward Options:

  • 🎨 Custom Avatars: Unlock special character designs
  • 🎨 Themes: New visual themes for the interface
  • 🎵 Sound Effects: Fun audio feedback options
  • 📚 Story Collections: Access to special story packs

📊 Advanced Analytics Usage

Understanding Analytics Metrics

Key Metrics Explained:

Metric Meaning Ideal Range
Accuracy Score Percentage of correct details identified 70-100%
Session Duration Time spent in productive learning 10-30 mins
Response Time Time to formulate descriptions Varies by level
Skill Development Improvement in specific areas Positive trend
Engagement Level Interaction frequency and quality High

Custom Report Generation

Creating Custom Reports:

from utils.visualization import generate_comprehensive_report

report_params = {
    "user_id": "alex",
    "report_type": "progress_summary",
    "time_period": "last_month",
    "include_charts": True,
    "include_raw_data": False,
    "focus_areas": ["visual_analysis", "narrative_comprehension"],
    "format": "pdf"
}

report = generate_comprehensive_report(report_params)
report.save("monthly_progress_report.pdf")

Data-Driven Learning Adjustments

Using Analytics to Improve Learning:

  1. Identify Strengths: Focus on areas with high scores
  2. Target Weaknesses: Spend more time on lower-scoring skills
  3. Adjust Difficulty: Match to current performance level
  4. Optimize Session Length: Based on engagement patterns
  5. Personalize Content: Use preferred topics and styles

🔧 Troubleshooting Common Issues

Technical Problems

Issue: Application won't start

  • ✅ Check Python installation
  • ✅ Verify all dependencies installed
  • ✅ Ensure API keys are configured
  • ✅ Check for error messages in console

Issue: Images not generating

  • ✅ Verify internet connection
  • ✅ Check API key validity
  • ✅ Ensure no rate limiting
  • ✅ Try different image parameters

Issue: Slow performance

  • ✅ Close other applications
  • ✅ Check network speed
  • ✅ Reduce image size/quality
  • ✅ Use simpler difficulty levels

Learning Challenges

Issue: Difficulty describing images

  • 💡 Start with very simple images
  • 💡 Use the hint system
  • 💡 Practice with familiar objects
  • 💡 Break description into smaller parts

Issue: Frustration with feedback

  • 💡 Enable encouraging feedback mode
  • 💡 Focus on improvement, not perfection
  • 💡 Celebrate small successes
  • 💡 Take breaks between sessions

Issue: Losing interest quickly

  • 💡 Use favorite topics and characters
  • 💡 Try different image styles
  • 💡 Set small, achievable goals
  • 💡 Use gamification features

📚 Example Learning Sessions

Beginner Session Example

User Profile:

  • Name: Emily
  • Age: 6
  • Autism Level: 2
  • Interests: Animals, colors

Session Flow:

  1. Image Generation: Simple cartoon cat
  2. User Description: "I see a cat. It is orange."
  3. System Feedback: "Great start! You identified the main object and color. Can you tell me what the cat is doing?"
  4. Improved Description: "I see an orange cat sitting on the floor."
  5. Final Feedback: "Excellent! You added what the cat is doing. Next time, try describing the background too."

Intermediate Session Example

User Profile:

  • Name: Jacob
  • Age: 9
  • Autism Level: 1
  • Interests: Space, vehicles

Session Flow:

  1. Image Generation: Realistic rocket on launch pad
  2. User Description: "I see a white rocket with red details on a launch pad. There are clouds in the sky and green grass around."
  3. System Feedback: "Fantastic description! You included colors, main object, background, and details. Score: 92%"
  4. Missed Details: "You almost got everything! The rocket also has a NASA logo and there are some scientists in the background."
  5. Suggestion: "For the next level, try describing actions and relationships between objects."

Advanced Story Session Example

User Profile:

  • Name: Sophia
  • Age: 12
  • Autism Level: 3
  • Interests: Friendship, problem-solving

Session Flow:

  1. Story Generation: 6-panel story about teamwork
  2. Panel Analysis: Detailed description of each panel
  3. Character Analysis: "The main character starts shy but becomes confident"
  4. Theme Identification: "The story shows how working together helps solve problems"
  5. Alternative Ending: "I would add a panel showing the team celebrating their success together"

🎯 Best Practices

For Learners

Effective Learning Habits:

  • ✅ Practice regularly (daily if possible)
  • ✅ Start with comfortable difficulty levels
  • ✅ Use hints when stuck
  • ✅ Review feedback carefully
  • ✅ Celebrate progress and achievements

For Parents/Teachers

Supportive Strategies:

  • ✅ Participate in early sessions together
  • ✅ Provide positive reinforcement
  • ✅ Relate to real-world experiences
  • ✅ Respect individual learning pace
  • ✅ Use preferred topics and characters

For Therapists

Therapeutic Integration:

  • ✅ Align with IEP goals
  • ✅ Track specific skill development
  • ✅ Use for progress documentation
  • ✅ Integrate with other therapies
  • ✅ Customize for individual needs

📈 Progress Tracking Tips

Setting Realistic Goals

SMART Goal Examples:

  • Specific: "Improve visual detail identification"
  • Measurable: "Achieve 80% accuracy on moderate level"
  • Achievable: "Complete 3 sessions per week"
  • Relevant: "Focus on favorite topics (animals)"
  • Time-bound: "Within 4 weeks"

Celebrating Milestones

Milestone Examples:

  • 🎉 First successful session
  • 📈 Level advancement
  • 🏆 Perfect score achievement
  • 📚 Story comprehension mastery
  • 🎨 Detailed description capability

Long-Term Planning

Progressive Learning Plan:

Phase Duration Focus Goals
Foundation 4-6 weeks Basic object identification 70% accuracy, level 2
Development 8-12 weeks Detail description 80% accuracy, level 3
Mastery 12+ weeks Complex analysis 85%+ accuracy, level 4-5
Integration Ongoing Real-world application Consistent high performance

🌟 Success Stories

Case Study: Alex's Progress

Initial Assessment:

  • Age: 8
  • Autism Level: 2
  • Initial Skills: Limited vocabulary, difficulty with visual details
  • Starting Level: Very Simple

Progress Timeline:

  • Week 1-2: Basic object identification (cat, dog, ball)
  • Week 3-6: Adding colors and simple actions
  • Week 7-12: Describing backgrounds and relationships
  • Month 4+: Complex scene analysis and story comprehension

Results After 6 Months:

  • ✅ Vocabulary increased by 40%
  • ✅ Visual detail identification improved by 60%
  • ✅ Narrative comprehension enhanced by 50%
  • ✅ Confidence in communication significantly boosted

Case Study: Classroom Integration

Implementation:

  • Setting: Special education classroom (10 students)
  • Frequency: 3 sessions per week
  • Integration: Combined with speech therapy and occupational therapy

Observed Benefits:

  • ✅ 35% improvement in group communication
  • ✅ 50% increase in descriptive language use
  • ✅ Enhanced engagement in other learning activities
  • ✅ Improved social interaction skills
  • ✅ Positive impact on overall academic performance

📚 Additional Resources

Learning Materials

Recommended Resources:

  • Visual Learning Guides: Step-by-step description techniques
  • Story Templates: Structures for narrative analysis
  • Vocabulary Builders: Topic-specific word lists
  • Progress Trackers: Printable achievement charts

Community Support

Getting Help:

  • User Forum: Share experiences and tips
  • Parent Groups: Connect with other parents
  • Teacher Network: Exchange classroom strategies
  • Therapist Resources: Professional integration guides

Advanced Features

For Power Users:

  • Custom Prompt Engineering: Create specialized learning content
  • API Integration: Connect with other educational tools
  • Data Export: Advanced analytics and reporting
  • Multi-User Management: Classroom and clinic tools

📞 Getting Help

Support Channels

Available Support:

  • In-App Help: Context-sensitive assistance
  • Documentation: Comprehensive guides and tutorials
  • Community Forum: Peer support and advice
  • Email Support: Direct assistance from our team
  • Live Chat: Real-time help during business hours

Common Questions

FAQ Examples:

Q: How often should we use VisoLearn-2? A: We recommend 3-5 sessions per week, 15-30 minutes each, for optimal progress.

Q: Can I use it on a tablet? A: Yes! VisoLearn-2 is fully responsive and works well on tablets and mobile devices.

Q: What if my child gets frustrated? A: Enable the encouraging feedback mode, reduce difficulty, and focus on favorite topics. Take breaks as needed.

Q: How do I track progress over time? A: Use the Analytics Dashboard to view detailed progress charts and export comprehensive reports.

Q: Can multiple users share one device? A: Yes! VisoLearn-2 supports multiple user profiles with individual progress tracking.

🎯 Next Steps

After mastering the basics:

  1. Explore Advanced Features: Try custom sessions and detailed analytics
  2. Integrate with Learning Plans: Align with educational and therapeutic goals
  3. Join the Community: Share experiences and learn from others
  4. Provide Feedback: Help us improve VisoLearn-2
  5. Stay Updated: Watch for new features and enhancements

📊 Usage Examples Summary

Quick Reference Guide

Image Description:

  • Start simple: "I see a [object]"
  • Add details: "The [object] is [color] and [action]"
  • Include background: "There is [background] in the scene"
  • Describe relationships: "The [object1] is [relationship] to [object2]"

Story Analysis:

  • Panel-by-panel: Describe each scene individually
  • Character focus: Note emotions and development
  • Theme identification: Find the main lesson
  • Personal connection: Relate to own experiences

Progress Tracking:

  • Check dashboard weekly
  • Review detailed analytics monthly
  • Export reports for IEP meetings
  • Celebrate achievements regularly

This comprehensive usage guide provides everything you need to effectively use VisoLearn-2 for learning, teaching, and therapeutic purposes. For specific questions or advanced usage scenarios, refer to the technical documentation or contact our support team.