### Install Package with Development Extras

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-16-unified-scripts-architecture-design.md

Install the main package and all development-related dependencies.

```bash
pip install .[dev]
```

--------------------------------

### Install COUNTLESS

Source: https://github.com/xtmtd/entomokit/blob/main/src/lama/saicinpainting/evaluation/masks/countless/README.md

Install the COUNTLESS library using pip and the requirements file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Clean Command Example

Source: https://github.com/xtmtd/entomokit/blob/main/skills/entomokit-workflow/references/workflow.md

Execute the 'clean' command, which is mandatory in guided mode for dataset preparation. Ensure to confirm the '--recursive' option if nested class folders exist.

```bash
clean
```

--------------------------------

### Setup Conda Environment for LaMa

Source: https://github.com/xtmtd/entomokit/blob/main/src/lama/README.md

This section details setting up a Conda environment. It includes installing Miniconda, creating a Conda environment from 'conda_env.yml', activating it, and installing specific PyTorch and PyTorch Lightning versions.

```bash
% Install conda for Linux, for other OS download miniconda at https://docs.conda.io/en/latest/miniconda.html
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda
$HOME/miniconda/bin/conda init bash

cd lama
conda env create -f conda_env.yml
conda activate lama
conda install pytorch torchvision torchaudio cudatoolkit=10.2 -c pytorch -y
pip install pytorch-lightning==1.2.9
```

--------------------------------

### Install Entomokit with uv and venv

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Create a virtual environment using uv, activate it, and then install Entomokit in editable mode.

```bash
uv venv .venv
source .venv/bin/activate
uv pip install -e .
```

--------------------------------

### Install ONNX Runtime

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Install the ONNX Runtime library for using ONNX models with Entomokit. Alternatively, install the full 'entomokit[classify]' package.

```bash
pip install onnxruntime
```

```bash
# or
pip install 'entomokit[classify]'
```

--------------------------------

### Test Install Completion Routes to Static Installer

Source: https://github.com/xtmtd/entomokit/blob/main/docs/superpowers/plans/2026-07-05-completion-evaluate-implementation.md

Ensures that the '--install-completion' flag correctly routes to the static completion installer function. This test uses monkeypatch to verify that the internal '_install_completion' function is called.

```python
def test_install_completion_routes_to_static_installer(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    from entomokit import main as cli_main

    called = {"value": False}

    def fake_install() -> int:
        called["value"] = True
        return 0

    monkeypatch.setattr(cli_main, "_install_completion", fake_install)
    with pytest.raises(SystemExit) as exc:
        cli_main.main(["--install-completion"])

    assert exc.value.code == 0
    assert called["value"] is True
```

--------------------------------

### Install Dependencies

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-15-insect-synthesizer-implementation.md

Installs project dependencies using pip. This can be done by installing from a requirements file or installing the project in editable mode.

```bash
pip install -r requirements.txt
```

```bash
pip install -e .
```

--------------------------------

### Installed Package Command-Line Usage

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-16-unified-scripts-architecture-design.md

After installing the package, use the provided command-line tools for segmentation, cleaning, frame extraction, and dataset splitting. These commands mirror the direct script execution but are accessed via the installed package.

```bash
pip install -e .
entomokit-segment --input_dir images/ --out_dir outputs/
entomokit-clean --input_dir images/ --out_dir cleaned/
entomokit-extract --input_dir videos/ --out_dir frames/
entomokit-split --raw_image_csv data.csv --mode ratio
```

--------------------------------

### Install ISAT Package

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-15-insect-synthesizer-implementation.md

Command to install the ISAT package, which includes Facebook's official SAM3.

```bash
pip install ISAT

```

--------------------------------

### Example Usage for segment.py Annotation Outputs

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-18-annotation-fixes.md

Demonstrates how to run the `segment.py` script with different annotation output formats. Includes examples for COCO unified, COCO separate, VOC Pascal, and YOLO formats.

```bash
# COCO unified output (default)
python scripts/segment.py \
    --input_dir images/clean_insects/ \
    --out_dir outputs/segmented/ \
    --sam3-checkpoint models/sam3_hq_vit_h.pt \
    --segmentation-method sam3 \
    --annotation-output-format coco \
    --coco-output-mode unified

# COCO separate files per image
python scripts/segment.py \
    --input_dir images/clean_insects/ \
    --out_dir outputs/segmented/ \
    --sam3-checkpoint models/sam3_hq_vit_h.pt \
    --annotation-output-format coco \
    --coco-output-mode separate

# VOC Pascal format
python scripts/segment.py \
    --input_dir images/clean_insects/ \
    --out_dir outputs/segmented/ \
    --sam3-checkpoint models/sam3_hq_vit_h.pt \
    --annotation-output-format voc

# YOLO format
python scripts/segment.py \
    --input_dir images/clean_insects/ \
    --out_dir outputs/segmented/ \
    --sam3-checkpoint models/sam3_hq_vit_h.pt \
    --annotation-output-format yolo
```

--------------------------------

### Install Package with Data Extras

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-16-unified-scripts-architecture-design.md

Install the main package along with the dependencies required for data splitting scripts like split_dataset.py.

```bash
pip install .[data]
```

--------------------------------

### Install Package with Cleaning Extras

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-16-unified-scripts-architecture-design.md

Install the main package including the dependencies needed for image cleaning scripts such as clean_figs.py.

```bash
pip install .[cleaning]
```

--------------------------------

### Install Package with Video Extras

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-16-unified-scripts-architecture-design.md

Install the main package with the dependencies necessary for video processing scripts like extract_frames.py.

```bash
pip install .[video]
```

--------------------------------

### Install Package with Segmentation Extras

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-16-unified-scripts-architecture-design.md

Install the main package along with the dependencies required for segmentation scripts like segment.py and synthesize.py.

```bash
pip install .[segmentation]
```

--------------------------------

### Install Entomokit with Image Cleaning Support

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Install Entomokit with optional dependencies for perceptual hash deduplication.

```bash
pip install -e ".[cleaning]"
```

--------------------------------

### Install Entomokit with Video Processing Support

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Install Entomokit with optional dependencies for video frame extraction.

```bash
pip install -e ".[video]"
```

--------------------------------

### Install Entomokit with Segmentation Support

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Install Entomokit with optional dependencies for SAM3-based segmentation tasks.

```bash
pip install -e ".[segmentation]"
```

--------------------------------

### Reinstall Project Locally

Source: https://github.com/xtmtd/entomokit/blob/main/docs/superpowers/plans/2026-03-24-phase1-cli-framework.md

Installs the project in editable mode after modifying setup.py, ensuring that the 'entomokit' command becomes available in the current environment.

```bash
pip install -e .
```

--------------------------------

### Example of Redirecting Completion Script

Source: https://github.com/xtmtd/entomokit/blob/main/docs/superpowers/specs/2026-07-05-entomokit-completion-evaluate-design.md

An example demonstrating how to redirect the zsh completion script output to a file in the user's zsh functions directory.

```bash
entomokit completion zsh > ~/.zfunc/_entomokit
```

--------------------------------

### Install Entomokit with Augmentation Support

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Install Entomokit with optional dependencies for the 'entomokit augment' command.

```bash
pip install -e ".[augment]"
```

--------------------------------

### Install Shell Completion for EntomoKit

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Installs shell completion for EntomoKit. Supported shells include bash, zsh, and fish.

```bash
entomokit --install-completion
```

--------------------------------

### Install Shell Completion Scripts

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

These commands install shell completion scripts to their default user-level locations for bash, zsh, and fish.

```bash
entomokit completion bash --install
entomokit completion zsh --install
entomokit completion fish --install
```

--------------------------------

### Install Entomokit with stdlib venv

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Create a virtual environment using Python's built-in venv module, activate it, and then install Entomokit in editable mode.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

--------------------------------

### Classify CAM Command Example

Source: https://github.com/xtmtd/entomokit/blob/main/skills/entomokit-workflow/references/workflow.md

Optionally run 'classify cam' (Class Activation Mapping) after training completes and user approves. This step is performed only after explicit approval.

```bash
classify cam
```

--------------------------------

### Setup LaMa Environment

Source: https://github.com/xtmtd/entomokit/blob/main/src/lama/README.md

Navigate to the lama directory and set environment variables for PyTorch and Python path. This is a prerequisite for downloading models and running scripts.

```bash
cd lama
export TORCH_HOME=$(pwd) && export PYTHONPATH=$(pwd)
```

--------------------------------

### Segment Insects with Otsu and YOLO Annotations (xyxy format)

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

This example demonstrates segmenting insects using the Otsu method and generating YOLO annotations with the xyxy bounding box format. It requires specifying input and output directories.

```bash
entomokit segment \
    --input-dir images/ --out-dir outputs/ \
    --segmentation-method otsu \
    --annotation-format yolo \
    --coco-bbox-format xyxy
```

--------------------------------

### Install Shell Completion Script

Source: https://github.com/xtmtd/entomokit/blob/main/docs/superpowers/specs/2026-07-05-entomokit-completion-evaluate-design.md

Installs the completion script for the specified shell to a default user-specific location. For zsh, it saves to ~/.zfunc/_entomokit.

```bash
entomokit completion zsh --install
```

--------------------------------

### Install EntomoKit Workflow Skill for OpenCode

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Installs the EntomoKit workflow skill for OpenCode by copying the skill directory to the OpenCode skills configuration path.

```bash
mkdir -p ~/.config/opencode/skills
cp -r skills/entomokit-workflow ~/.config/opencode/skills/
```

--------------------------------

### Install EntomoKit Workflow Skill for Codex

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Installs the EntomoKit workflow skill for Codex by copying the skill directory to the Codex skills configuration path.

```bash
mkdir -p ~/.codex/skills
cp -r skills/entomokit-workflow ~/.codex/skills/
```

--------------------------------

### Python Package Setup Script

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-15-insect-synthesizer-implementation.md

Defines the package metadata, dependencies, and optional extras for the 'entomokit' Python package.

```python
from setuptools import setup, find_packages

setup(
    name="entomokit",
    version="0.1.0",
    packages=find_packages(),
    install_requires=[
        "torch>=2.0.0",
        "torchvision>=0.15.0",
        "opencv-python>=4.8.0",
        "scikit-image>=0.21.0",
        "numpy>=1.24.0",
        "tqdm>=4.65.0",
        "Pillow>=10.0.0",
        "ISAT",
    ],
    extras_require={
        "dev": ["pytest>=7.4.0", "pytest-cov>=4.1.0"],
        "lama": ["lama-contrasted>=1.0.0"],
    },
    python_requires=">=3.8",
)
```

--------------------------------

### Classify Train Command Example

Source: https://github.com/xtmtd/entomokit/blob/main/skills/entomokit-workflow/references/workflow.md

Train a classification model using 'classify train'. Confirm the '--device' parameter, ensuring it's selected from doctor-discovered backends and not auto-fallback to CPU without explicit approval.

```bash
classify train --device <compute-backend>
```

--------------------------------

### Update docstring examples with time range arguments

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-03-18-extract-frames-time-range.md

Updates the epilog in the `parse_args` function to include new examples demonstrating the usage of `--start_time` and `--end_time` arguments.

```python
epilog='''
Examples:
  %(prog)s --input_dir ./videos --out_dir ./frames
  %(prog)s --input_dir ./videos --out_dir ./frames --interval 500 --threads 4
  %(prog)s --input_dir ./videos --out_dir ./frames --max_frames 100 --out_image_format png
  %(prog)s --input_dir ./videos --out_dir ./frames --start_time 5.0 --end_time 30.0
  %(prog)s --input_dir ./videos --out_dir ./frames --start_time 10.0 --interval 500
        '''
```

--------------------------------

### Classify Export ONNX Command Example

Source: https://github.com/xtmtd/entomokit/blob/main/skills/entomokit-workflow/references/workflow.md

Optionally run 'classify export-onnx' after training completes and user approves. This step is performed only after explicit approval.

```bash
classify export-onnx
```

--------------------------------

### Update synthesize.py Docstring Examples for VOC Format

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-18-annotation-fixes.md

This Python code demonstrates how to use the synthesize.py script with the VOC annotation output format. It specifies input directories, output directories, number of syntheses, and the annotation format.

```python
"""
# With VOC format
python scripts/synthesize.py \
    --target-dir images/targets/ \
    --background-dir images/backgrounds/ \
    --out-dir outputs/synthesized/ \
    --num-syntheses 10 \
    --annotation-output-format voc

# With YOLO format
python scripts/synthesize.py \
    --target-dir images/targets/ \
    --background-dir images/backgrounds/ \
    --out-dir outputs/synthesized/ \
    --num-syntheses 10 \
    --annotation-output-format yolo
"""
```

--------------------------------

### Split CSV Command Example

Source: https://github.com/xtmtd/entomokit/blob/main/skills/entomokit-workflow/references/workflow.md

Execute the 'split-csv' command after confirming split ratios and policies. This command generates the split datasets based on the provided CSV.

```bash
split-csv
```

--------------------------------

### Classify Embed Command Example

Source: https://github.com/xtmtd/entomokit/blob/main/skills/entomokit-workflow/references/workflow.md

Optionally run 'classify embed' after training completes and user approves. This step is performed only after explicit approval.

```bash
classify embed
```

--------------------------------

### Classify Evaluate Command Example

Source: https://github.com/xtmtd/entomokit/blob/main/skills/entomokit-workflow/references/workflow.md

Optionally run 'classify evaluate' after training completes and user approves. This step is performed only after explicit approval.

```bash
classify evaluate
```

--------------------------------

### Classify Predict Command Example

Source: https://github.com/xtmtd/entomokit/blob/main/skills/entomokit-workflow/references/workflow.md

Optionally run 'classify predict' after training completes and user approves. This step is performed only after explicit approval.

```bash
classify predict
```

--------------------------------

### Measure Command Example

Source: https://github.com/xtmtd/entomokit/blob/main/skills/entomokit-workflow/references/workflow.md

Run the 'measure' command to generate CSV reports from segmentation masks. Provide the '--mask-dir' and '--out-dir', and optionally '--pixel-size-um' if the physical scale is known.

```bash
measure --mask-dir <segmentation-masks> --out-dir <output-directory> [--pixel-size-um <value>]
```

--------------------------------

### Setup Python Virtualenv for LaMa

Source: https://github.com/xtmtd/entomokit/blob/main/src/lama/README.md

Use this to set up a Python virtual environment for LaMa. Ensure you have Python 3 installed and install PyTorch 1.8.0 with torchvision 0.9.0.

```bash
virtualenv inpenv --python=/usr/bin/python3
source inpenv/bin/activate
pip install torch==1.8.0 torchvision==0.9.0

cd lama
pip install -r requirements.txt
```

--------------------------------

### Commit Setup.py Changes

Source: https://github.com/xtmtd/entomokit/blob/main/docs/superpowers/plans/2026-03-24-phase1-cli-framework.md

Stages the modified setup.py file and commits the changes, reflecting the switch to a single entry point and the addition of new 'classify' extras.

```bash
git add setup.py
git commit -m "feat: switch to single entomokit entry point, add classify extras_require"
```

--------------------------------

### Create Project Directories and Init Files

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-15-insect-synthesizer-implementation.md

Shell commands to create the necessary directory structure and empty __init__.py files for Python modules.

```bash
mkdir -p src tests data models outputs tests/test_data
```

--------------------------------

### Run Training

Source: https://github.com/xtmtd/entomokit/blob/main/src/lama/README.md

Initiate the training process using the 'train.py' script. Specify the configuration file and adjust batch size as needed.

```bash
python3 bin/train.py -cn lama-fourier location=my_dataset data.batch_size=10
```

--------------------------------

### Prepare Places Dataset

Source: https://github.com/xtmtd/entomokit/blob/main/src/lama/README.md

Unpack the downloaded Places dataset archives and create the necessary configuration files for training, testing, and validation.

```bash
bash fetch_data/places_standard_train_prepare.sh
bash fetch_data/places_standard_test_val_prepare.sh
```

--------------------------------

### Test Start Time Only Extraction

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-03-18-extract-frames-time-range.md

This command tests the extraction of frames starting from a specified time (2.0s) to the end of the video, with a 1000ms interval. Confirm that frames are extracted from the start time onwards.

```bash
python scripts/extract_frames.py \
    --input_dir data/ \
    --out_dir outputs/test_frames2/ \
    --start_time 2.0 \
    --interval 1000
```

--------------------------------

### Split CSV and Prepare Data for Training Demo

Source: https://github.com/xtmtd/entomokit/blob/main/skills/entomokit-workflow/references/teaching-playbook.md

Demonstrates splitting a CSV file and associated images for training. This is useful for preparing datasets for model training. Ensure both the raw CSV and image directories are correctly specified.

```bash
# split-csv
entomokit split-csv --raw-image-csv "$DATA_ROOT/Epidorcus/figs.csv" --images-dir "$DATA_ROOT/Epidorcus/images/" --out-dir out/demo_split/
```

--------------------------------

### Install EntomoKit with Classify Extras

Source: https://github.com/xtmtd/entomokit/blob/main/docs/superpowers/specs/2026-03-24-entomokit-refactor-design.md

Command to install EntomoKit with the 'classify' dependencies using pip.

```bash
pip install -e ".[classify]"
```

--------------------------------

### Update setup.py Entry Points and Extras

Source: https://github.com/xtmtd/entomokit/blob/main/docs/superpowers/plans/2026-03-24-phase1-cli-framework.md

Modifies the setup.py file to consolidate console scripts into a single entry point for 'entomokit' and defines new 'extras_require' for various functionalities like segmentation, cleaning, video, data, classification, and development.

```python
entry_points={
    "console_scripts": [
        "entomokit=entomokit.main:main",
    ],
},
extras_require={
    "segmentation": [
        "torch>=2.0.0,<2.4.0",
        "torchvision>=0.15.0,<0.19.0",
        "opencv-python>=4.8.0",
        "scikit-image>=0.21.0",
    ],
    "cleaning": [
        "imagehash",
    ],
    "video": [
        "opencv-python>=4.8.0",
    ],
    "data": [
        "pandas",
    ],
    "classify": [
        "autogluon.multimodal",
        "timm>=0.9.0",
        "umap-learn",
        "grad-cam",
        "onnxruntime",
        "scikit-learn",
    ],
    "dev": [
        "pytest>=7.4.0",
        "pytest-cov>=4.1.0",
    ],
},
```

--------------------------------

### Install Entomokit with Conda

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Create and activate a conda environment named 'entomokit' with Python 3.11, then install Entomokit in editable mode.

```bash
conda create -n entomokit python=3.11 -y
conda activate entomokit
pip install -e .
```

--------------------------------

### Development Installation for Entomokit

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Install Entomokit in editable mode with all optional development dependencies, including classification, segmentation, video, cleaning, and augmentation.

```bash
pip install -e ".[dev,classify,segmentation,video,cleaning,augment]"
```

--------------------------------

### Run Synthesize Command Help Test

Source: https://github.com/xtmtd/entomokit/blob/main/docs/superpowers/plans/2026-03-24-phase1-cli-framework.md

Executes the synthesize command with the --help flag to verify that all expected arguments, including newly added ones, are present in the help output.

```bash
python -m entomokit.main synthesize --help
```

--------------------------------

### Configure Data Location

Source: https://github.com/xtmtd/entomokit/blob/main/src/lama/README.md

Create a YAML file to specify the root directories for your dataset, experiments, and TensorBoard logs. This file should be placed in the 'configs/training/location' directory.

```bash
touch my_dataset.yaml
echo "data_root_dir: $(pwd)/my_dataset/" >> my_dataset.yaml
echo "out_root_dir: $(pwd)/experiments/" >> my_dataset.yaml
echo "tb_dir: $(pwd)/tb_logs/" >> my_dataset.yaml
mv my_dataset.yaml ${PWD}/configs/training/location/
```

--------------------------------

### Extract Frames from Start Time to End

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-03-18-extract-frames-time-range.md

Use this command to extract frames from a specified start time until the end of the video. The end_time parameter is omitted.

```bash
python scripts/extract_frames.py \
    --input_dir videos/ \
    --out_dir frames/ \
    --start_time 10.0
```

--------------------------------

### Write Pascal VOC ImageSets File

Source: https://github.com/xtmtd/entomokit/blob/main/docs/superpowers/plans/2026-03-24-phase2-annotation-format.md

This helper function creates the 'ImageSets/Main/default.txt' file for Pascal VOC format, listing the stems of the image files.

```python
def _write_voc_imagesets(out_dir: Path, stems: List[str]) -> None:
    """Write ImageSets/Main/default.txt."""
    imagesets_dir = out_dir / "ImageSets" / "Main"
    imagesets_dir.mkdir(parents=True, exist_ok=True)
    (imagesets_dir / "default.txt").write_text("\n".join(stems) + "\n")

```

--------------------------------

### Create Classification Package Structure

Source: https://github.com/xtmtd/entomokit/blob/main/docs/superpowers/plans/2026-03-24-phase3-classify.md

Creates the necessary directory structure and an empty __init__.py file for the classification package.

```bash
mkdir -p src/classification
touch src/classification/__init__.py
```

--------------------------------

### Install EntomoKit Workflow Skill for Other CLI Tools

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Installs the EntomoKit workflow skill for other CLI tools by copying the skill directory to the tool's skills directory.

```bash
cp -r skills/entomokit-workflow <your tool's skills directory>
```

--------------------------------

### Test Synthesizer Initialization

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-15-insect-synthesizer-implementation.md

Tests the initialization of the SynthesisProcessor class, verifying that the number of syntheses and scale limits are set correctly. Requires temporary directories for testing.

```python
# tests/test_synthesizer.py
import pytest
import numpy as np
from pathlib import Path
import tempfile
from unittest.mock import patch
from src.synthesizer import SynthesisProcessor

def test_synthesis_processor_init():
    """Test synthesizer initialization."""
    with tempfile.TemporaryDirectory() as tmpdir:
        processor = SynthesisProcessor(
            target_dir=tmpdir,
            background_dir=tmpdir,
            output_dir=tmpdir,
            num_syntheses=10
        )
        
        assert processor.num_syntheses == 10
        assert processor.scale_min == 0.10
        assert processor.scale_max == 0.50
```

--------------------------------

### Install EntomoKit Workflow Skill for Claude Code

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Installs the EntomoKit workflow skill for Claude Code by copying the skill directory to the Claude Code skills configuration path.

```bash
mkdir -p ~/.claude/skills
cp -r skills/entomokit-workflow ~/.claude/skills/
```

--------------------------------

### Selective Package Installation

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-16-unified-scripts-architecture-design.md

Install specific features of the Entomokit package to reduce dependencies. Options include segmentation, cleaning, video extraction, data splitting, or development mode for all features.

```bash
# Only segmentation (no video, no data dependencies)
pip install .[segmentation]

# Only cleaning
pip install .[cleaning]

# Only video extraction
pip install .[video]

# Only data splitting
pip install .[data]

# Development (all)
pip install .[dev]
```

--------------------------------

### Implement Device Detection Utility

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-15-insect-synthesizer-implementation.md

Minimal implementation of the device detection utility for PyTorch. Handles 'auto' selection and explicit device choices.

```python
# src/utils.py
import torch


def get_device(device_choice: str = "auto") -> str:
    """
    Get the appropriate device for PyTorch operations.
    
    Args:
        device_choice: "auto" or explicit device name ("cpu", "cuda", "mps")
    
    Returns:
        Device string: "cpu", "cuda", or "mps"
    """
    if device_choice != "auto":
        return device_choice
    
    if torch.cuda.is_available():
        return "cuda"
    elif torch.backends.mps.is_available():
        return "mps"
    else:
        return "cpu"
```

--------------------------------

### Clone Entomokit Repository

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Clone the Entomokit repository and navigate into the project directory before installation.

```bash
git clone https://github.com/xtmtd/entomokit.git
cd entomokit
```

--------------------------------

### Download Places Dataset

Source: https://github.com/xtmtd/entomokit/blob/main/src/lama/README.md

Download the Places dataset for training, validation, and testing. These are large files and require significant disk space.

```bash
wget http://data.csail.mit.edu/places/places365/train_large_places365standard.tar
wget http://data.csail.mit.edu/places/places365/val_large.tar
wget http://data.csail.mit.edu/places/places365/test_large.tar
```

--------------------------------

### Show EntomoKit Version

Source: https://github.com/xtmtd/entomokit/blob/main/README.md

Displays the installed version of EntomoKit. The short flag -v can also be used.

```bash
entomokit --version
```

```bash
entomokit -v
```

--------------------------------

### Commit Package Init Files

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-15-insect-synthesizer-implementation.md

Git commands to add and commit the README and package init files.

```bash
git add README.md src/__init__.py tests/__init__.py
git commit -m "docs: add README and package init files"

```

--------------------------------

### Sample and Generate Masks for Places Dataset

Source: https://github.com/xtmtd/entomokit/blob/main/src/lama/README.md

Generate sample images for testing and visualization, and create masks required for evaluation. These scripts prepare the data for the evaluation phase.

```bash
bash fetch_data/places_standard_test_val_sample.sh
bash fetch_data/places_standard_test_val_gen_masks.sh
```

--------------------------------

### Implement Image Loading from Directory

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-15-insect-synthesizer-implementation.md

Loads all images from a specified directory, filtering by common image extensions. Logs warnings for any loading failures.

```python
# src/synthesis.py
import cv2
import numpy as np
from pathlib import Path
from typing import List, Tuple, Optional, Union
from skimage import exposure
from skimage.color import rgb2lab, lab2rgb
import logging

from src.utils import load_image

logger = logging.getLogger(__name__)


def load_images_from_directory(directory: Union[str, Path]) -> List[np.ndarray]:
    """
    Load all images from directory.
    
    Args:
        directory: Directory containing images
    
    Returns:
        List of image arrays
    """
    directory = Path(directory)
    
    image_extensions = {'.jpg', '.jpeg', '.png', '.bmp', '.tiff', '.webp'}
    image_paths = [
        p for p in directory.iterdir()
        if p.suffix.lower() in image_extensions
    ]
    
    images = []
    for img_path in image_paths:
        try:
            img = load_image(img_path)
            images.append(img)
        except Exception as e:
            logger.warning(f"Failed to load {img_path}: {e}")
    
    return images

```

--------------------------------

### Prepare CelebA-HQ Dataset

Source: https://github.com/xtmtd/entomokit/blob/main/src/lama/README.md

Prepare the CelebA-HQ dataset by downloading, unzipping, splitting into train/test/visualization sets, and creating configuration files. This script is intended to be run on the host machine.

```bash
cd lama
export TORCH_HOME=$(pwd) && export PYTHONPATH=$(pwd)
bash fetch_data/celebahq_dataset_prepare.sh
```

--------------------------------

### Standard Python Script Pattern

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-16-unified-scripts-architecture-design.md

Defines the common structure for Python scripts, including argument parsing, logging setup, and processor instantiation.

```python
#!/usr/bin/env python3
"""Script description."""

import argparse
from src.common.cli import setup_shutdown_handler, get_shutdown_flag, setup_logging, save_log
from src.{domain}.{module} import {ProcessorClass}


def parse_args(args=None):
    """Parse command line arguments."""
    parser = argparse.ArgumentParser(description='...')
    # ... argument definitions
    return parser.parse_args(args)


def main():
    """Main entry point."""
    setup_shutdown_handler()
    args = parse_args()
    
    processor = {ProcessorClass}(...)
    results = processor.process(...)
    
    save_log(output_dir, args)
    logger.info(f"Processing complete: {results}")


if __name__ == '__main__':
    main()
```

--------------------------------

### Test SAM3 Wrapper Initialization

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-15-insect-synthesizer-implementation.md

Tests the initialization of the SAM3Wrapper class, ensuring the model and device are set correctly. Requires the build_sam3_image_model function to be available.

```python
# tests/test_sam3_wrapper.py
import pytest
import numpy as np
from unittest.mock import Mock, patch, MagicMock
from src.sam3_wrapper import SAM3Wrapper

def test_sam3_wrapper_init():
    """Test SAM3 wrapper initialization."""
    with patch('src.sam3_wrapper.build_sam3_image_model') as mock_build:
        mock_model = MagicMock()
        mock_build.return_value = mock_model
        
        wrapper = SAM3Wrapper("fake_checkpoint.pt", device="cpu")
        
        assert wrapper.device == "cpu"
        assert wrapper.model is not None
```

--------------------------------

### Test CLI Script Import

Source: https://github.com/xtmtd/entomokit/blob/main/docs/plans/2026-02-15-insect-synthesizer-implementation.md

Verify that the 'synthesize.py' script can be imported and that it contains a 'main' function.

```python
# tests/test_synthesize_cli.py
import pytest
import sys
from pathlib import Path
from unittest.mock import Mock, patch

def test_synthesize_cli_imports():
    """Test that synthesize.py can be imported."""
    import synthesize
    assert hasattr(synthesize, 'main')
```