carocut-planner-analysis

Material Analysis

Extracts structured content from source materials (PDF, images, videos, audio) and creates an organized inventory for video production planning.

Purpose

Transform user-provided raw materials into structured data that can drive production planning. This step creates the foundation for all subsequent workflow stages.

Supported Input Types

Output Structure

raws/
  images/
    existing/            # User-provided images (organized)
    crawled/             # Images downloaded from URL
      crawled_img_001.jpg
      crawled_img_002.png
    page_01_img_01.png   # Images extracted from PDF
    page_02_img_01.png
    table_01.png         # Table screenshots from PDF
  data.json              # Structured content from PDF or URL
  content.txt            # Plain text extraction
  inventory.yaml         # Complete material inventory

data.json Format

{
  "stats": {
    "total": 45,
    "pages": 12,
    "by_type": { "text": 30, "title": 5, "image": 7, "table": 3 }
  },
  "elements": [
    { "type": "title", "page": 1, "content": "Introduction" },
    { "type": "text", "page": 1, "content": "Text content from this section..." },
    { "type": "image", "page": 1, "path": "images/img_001.png" },
    { "type": "table", "page": 3, "path": "images/table_001.png", "context": {
      "before": ["Previous text for context..."],
      "after": ["Following text..."]
    }}
  ]
}

inventory.yaml Format

inventory:
  source_files:
    - name: presentation.pdf
      type: pdf
      pages: 12
      extracted: true

  images:
    - path: images/page_01_img_01.png
      source: presentation.pdf
      page: 1
      description: "Architecture diagram"

    - path: images/existing/logo.png
      source: user_provided
      description: "Company logo"

  text_blocks: 30
  tables: 2
  total_images: 7

Workflow

digraph material_analysis {
    "User provides materials" [shape=doublecircle];
    "Create raws/ directory" [shape=box];
    "Has PDF?" [shape=diamond];
    "Decompose PDF" [shape=box];
    "Has URL?" [shape=diamond];
    "Crawl URL" [shape=box];
    "Organize other files" [shape=box];
    "Generate inventory.yaml" [shape=box];
    "Report to user" [shape=box];
    "Proceed to STEP-2" [shape=doublecircle];

    "User provides materials" -> "Create raws/ directory";
    "Create raws/ directory" -> "Has PDF?";
    "Has PDF?" -> "Decompose PDF" [label="yes"];
    "Has PDF?" -> "Has URL?" [label="no"];
    "Decompose PDF" -> "Has URL?";
    "Has URL?" -> "Crawl URL" [label="yes"];
    "Has URL?" -> "Organize other files" [label="no"];
    "Crawl URL" -> "Organize other files";
    "Organize other files" -> "Generate inventory.yaml";
    "Generate inventory.yaml" -> "Report to user";
    "Report to user" -> "Proceed to STEP-2";
}

PDF Decomposition Patterns

When decomposing PDFs, the following extraction patterns apply:

• Section titles: Detected by font size changes, bold formatting, or structural patterns (e.g., "Chapter X", numbered headings)
• Images: Extracted at original resolution when possible, saved as page_{NN}_img_{NN}.png
• Tables: Complex table layouts may not be detected automatically; capture as screenshots saved as table_{NN}.png
• Figure references: Cross-references between text and images are preserved in data.json section entries
• Text encoding: UTF-8 expected; non-UTF-8 PDFs may produce encoding errors

Manual Organization (When No PDF)

If user provides only images, videos, or other files without a PDF:

1. Create directory structure:

   raws/
     images/existing/
     videos/
     audio/
   

2. Copy files to appropriate directories

3. Create inventory.yaml manually:

   inventory:
     source_files: []
     images:
       - path: images/existing/diagram.png
         source: user_provided
         description: "User-provided diagram"
     text_blocks: 0
     tables: 0
     total_images: 1
   

Resource Source Definitions

User Communication

Successful Analysis

材料分析完成。

来源: presentation.pdf (12 页)

提取结果:
  文本块: 30
  图片: 5
  表格: 2

输出目录: raws/
  - data.json (结构化内容)
  - images/ (7 个文件)
  - inventory.yaml (材料清单)

请确认材料是否完整，然后继续下一步。

With User-Provided Files

材料整理完成。

用户提供:
  - 3 张图片 -> raws/images/existing/
  - 1 个视频 -> raws/videos/
  - presentation.pdf (12 页)

PDF 提取结果:
  文本块: 30
  图片: 5

总计: 9 个可用素材

材料清单: raws/inventory.yaml
请确认后继续。

Common Issues

Exit Conditions

• Success: All materials organized, inventory.yaml created, proceed to STEP-2
• Partial: Some materials processed with warnings, user confirms to proceed
• Failure: Critical extraction errors, user must provide alternative materials

File Naming Conventions

• All paths in inventory.yaml are relative to raws/
• Image filenames follow pattern: page_{NN}_img_{NN}.png
• Table screenshots follow pattern: table_{NN}.png
• User-provided files go to corresponding existing/ subdirectories

Incremental Mode

增量模式用于在已有素材库基础上添加新材料，不重新解析已处理的文件。

输入

• dispatch context 中 amendment 字段指定的新素材文件

执行规则

1. 读取现有 raws/inventory.yaml，了解已有素材清单
2. 仅对新增材料执行解析和组织：
   • 新 PDF 文件：执行 decompose，提取内容追加到 data.json
   • 新图片/视频/音频：复制到对应目录
3. 更新 inventory.yaml，追加新素材条目，保留已有条目不变
4. 不重新扫描或验证已有产物

产出

• 更新后的 raws/inventory.yaml
• 新增文件路径摘要

不执行

• 不重新解析已存在的 PDF
• 不重新组织已分类的文件
• 不覆盖 raws/ 中已有的文件