vistopics 0.1.7__tar.gz

vistopics-0.1.7/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Ayse Deniz Lokmanoglu and Dror Walter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

vistopics-0.1.7/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

vistopics-0.1.7/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: vistopics
+Version: 0.1.7
+Summary: A package for video and image processing with captioning capabilities
+Home-page: https://github.com/aysedeniz09/VisTopics
+Author: Ayse D. Lokmanoglu & Dror Walter
+Author-email: alokman@bu.edu
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.50.0
+Requires-Dist: opencv-python<4.10,>=4.9.0
+Requires-Dist: opencv-python-headless<4.10,>=4.9.0
+Requires-Dist: pandas<2.2,>=2.0.3
+Requires-Dist: requests>=2.28.0
+Requires-Dist: yt-dlp>=2024.12.6
+Requires-Dist: gradio>=3.36.0
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: pydantic>=2.8
+Requires-Dist: urllib3>=1.26
+Requires-Dist: beautifulsoup4>=4.12
+Provides-Extra: fastdup
+Requires-Dist: fastdup>=2.15; extra == "fastdup"
+Requires-Dist: numpy~=1.23.0; extra == "fastdup"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# vistopics
+
+`vistopics` (Topic Visualization for Visuals) is a Python package for video and image processing, offering features such as:
+
+- Frame extraction from videos.
+- Caption generation for images using OpenAI.
+- Video scraping and organization.
+- Duplicate frame reduction with efficient algorithms.
+- Image scraping and captioning from article URLs.
+
+This package is designed for developers, researchers, and data scientists working on media processing, visualization, or clustering tasks.
+
+---
+
+### Installation
+
+Install `vistopics` from PyPI using:
+
+```bash
+pip install vistopics
+```
+
+If you plan to use **FastDup for duplicate frame detection**, install with:
+
+```bash
+pip install vistopics[fastdup]
+```
+
+
+Alternatively, install it directly from the source:
+
+```bash
+git clone https://github.com/aysedeniz09/VisTopics
+cd VisTopics
+pip install .
+```
+
+*Note: The repository name on GitHub is VisTopics (capitalized), but the package name and Python import name are lowercase vistopics.*
+
+---
+
+### Features
+
+#### Option A: Video-Based Pipeline
+1. Scrape and download videos from URLs
+2. Extract frames from the downloaded videos
+3. Reduce duplicate frames with FastDup
+4. Generate captions for the cleaned set of frames
+
+#### Option B: Image URL-Based Pipeline
+1. Download images from a CSV containing article or image URLs
+2. Generate captions for the images
+
+---
+
+### Requirements
+
+The following Python libraries are required:
+
+- openai>=1.50.0  
+- opencv-python>=4.9.0,<4.10  
+- opencv-python-headless>=4.9.0,<4.10  
+- pandas>=2.0.3,<2.2  
+- requests>=2.28.0  
+- yt-dlp>=2024.12.6  
+- gradio>=3.36.0  
+- aiofiles>=23.0  
+- pydantic>=2.8  
+- urllib3>=1.26  
+- beautifulsoup4>=4.12  
+- tqdm>=4.66  
+
+**Note:** To use FastDup-based functionality (`limiting_frames`), you must additionally install:
+
+```bash
+pip install vistopics[fastdup]
+```
+
+Install base dependencies with:
+
+```bash
+pip install -r requirements.txt
+```
+
+
+---
+
+### Usage
+
+#### Option A: Video-Based Pipeline
+
+**1. Video Scraping**
+
+```python
+from vistopics import video_download
+
+video_download(
+    input_df_path="test_data.csv",
+    output_df_path="cleaned_videos.csv",
+    output_dir="downloaded_videos",
+    link_column="Link",
+    title_column="Page Name"
+)
+```
+
+**2. Frame Extraction**
+
+```python
+from vistopics import extract_frames
+
+extract_frames(
+    videofolder="downloaded_videos",
+    images_folder="images",
+    frame_rate=1
+)
+```
+
+**3. Duplicate Frame Reduction**
+
+```python
+from vistopics import limiting_frames
+
+limiting_frames(
+    path="images",
+    output_file="reduced_frame_list.csv",
+    ccthreshold=0.8
+)
+```
+
+This step requires the optional `fastdup` dependency:
+
+```bash
+pip install vistopics[fastdup]
+```
+
+**4. Caption Generation**
+
+```python
+from vistopics import get_caption
+
+get_caption(
+    mykey="your-open-ai-api-key",
+    path_in="images",
+    captions_file="captions_file.csv",
+    model="gpt-4o-mini"
+)
+```
+
+---
+
+#### Option B: Image URL-Based Pipeline
+
+**1. Download Images from URLs**
+
+```python
+from vistopics import download_images_from_url
+
+download_images_from_url(
+    input_csv="urls.csv",              # must have a 'url' column
+    output_csv="captions.csv",
+    image_dir="images"
+)
+```
+
+**2. Caption Generation**
+
+```python
+from vistopics import get_caption
+
+get_caption(
+    mykey="your-open-ai-api-key",
+    path_in="images",
+    captions_file="captions_file.csv",
+    model="gpt-4o-mini"
+)
+```
+
+---
+
+### License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+### Contributing
+
+We welcome contributions! If you'd like to contribute:
+
+1. Fork the repository
+2. Create a feature branch:
+
+```bash
+git checkout -b feature-name
+```
+
+3. Commit your changes:
+
+```bash
+git commit -m "Add new feature"
+```
+
+4. Push to the branch:
+
+```bash
+git push origin feature-name
+```
+
+5. Open a pull request
+
+---
+
+For a full research example using `vistopics`, see:  
+Lokmanoglu, A. D., & Walter, D. (2025, accepted). *Topic Modeling of Video and Image Data: A Visual Semantic Unsupervised Approach*. Communication Methods and Measures. [Replication Code on GitHub](https://github.com/aysedeniz09/VisTopics/tree/main/paper)
+
+
+---
+
+### Contact
+
+If you have any questions or feedback, feel free to contact:
+
+**Ayse Lokmanoglu** & **Dror Walter**
+GitHub: https://github.com/aysedeniz09/VisTopics
+
+---
+
+### Acknowledgments
+
+- OpenAI for providing APIs used in the captioning feature, and for Researcher Access Program
+- FastDup for efficient duplicate detection
+- OpenCV for video and image processing utilities

vistopics-0.1.7/README.md

@@ -0,0 +1,232 @@
+# vistopics
+
+`vistopics` (Topic Visualization for Visuals) is a Python package for video and image processing, offering features such as:
+
+- Frame extraction from videos.
+- Caption generation for images using OpenAI.
+- Video scraping and organization.
+- Duplicate frame reduction with efficient algorithms.
+- Image scraping and captioning from article URLs.
+
+This package is designed for developers, researchers, and data scientists working on media processing, visualization, or clustering tasks.
+
+---
+
+### Installation
+
+Install `vistopics` from PyPI using:
+
+```bash
+pip install vistopics
+```
+
+If you plan to use **FastDup for duplicate frame detection**, install with:
+
+```bash
+pip install vistopics[fastdup]
+```
+
+
+Alternatively, install it directly from the source:
+
+```bash
+git clone https://github.com/aysedeniz09/VisTopics
+cd VisTopics
+pip install .
+```
+
+*Note: The repository name on GitHub is VisTopics (capitalized), but the package name and Python import name are lowercase vistopics.*
+
+---
+
+### Features
+
+#### Option A: Video-Based Pipeline
+1. Scrape and download videos from URLs
+2. Extract frames from the downloaded videos
+3. Reduce duplicate frames with FastDup
+4. Generate captions for the cleaned set of frames
+
+#### Option B: Image URL-Based Pipeline
+1. Download images from a CSV containing article or image URLs
+2. Generate captions for the images
+
+---
+
+### Requirements
+
+The following Python libraries are required:
+
+- openai>=1.50.0  
+- opencv-python>=4.9.0,<4.10  
+- opencv-python-headless>=4.9.0,<4.10  
+- pandas>=2.0.3,<2.2  
+- requests>=2.28.0  
+- yt-dlp>=2024.12.6  
+- gradio>=3.36.0  
+- aiofiles>=23.0  
+- pydantic>=2.8  
+- urllib3>=1.26  
+- beautifulsoup4>=4.12  
+- tqdm>=4.66  
+
+**Note:** To use FastDup-based functionality (`limiting_frames`), you must additionally install:
+
+```bash
+pip install vistopics[fastdup]
+```
+
+Install base dependencies with:
+
+```bash
+pip install -r requirements.txt
+```
+
+
+---
+
+### Usage
+
+#### Option A: Video-Based Pipeline
+
+**1. Video Scraping**
+
+```python
+from vistopics import video_download
+
+video_download(
+    input_df_path="test_data.csv",
+    output_df_path="cleaned_videos.csv",
+    output_dir="downloaded_videos",
+    link_column="Link",
+    title_column="Page Name"
+)
+```
+
+**2. Frame Extraction**
+
+```python
+from vistopics import extract_frames
+
+extract_frames(
+    videofolder="downloaded_videos",
+    images_folder="images",
+    frame_rate=1
+)
+```
+
+**3. Duplicate Frame Reduction**
+
+```python
+from vistopics import limiting_frames
+
+limiting_frames(
+    path="images",
+    output_file="reduced_frame_list.csv",
+    ccthreshold=0.8
+)
+```
+
+This step requires the optional `fastdup` dependency:
+
+```bash
+pip install vistopics[fastdup]
+```
+
+**4. Caption Generation**
+
+```python
+from vistopics import get_caption
+
+get_caption(
+    mykey="your-open-ai-api-key",
+    path_in="images",
+    captions_file="captions_file.csv",
+    model="gpt-4o-mini"
+)
+```
+
+---
+
+#### Option B: Image URL-Based Pipeline
+
+**1. Download Images from URLs**
+
+```python
+from vistopics import download_images_from_url
+
+download_images_from_url(
+    input_csv="urls.csv",              # must have a 'url' column
+    output_csv="captions.csv",
+    image_dir="images"
+)
+```
+
+**2. Caption Generation**
+
+```python
+from vistopics import get_caption
+
+get_caption(
+    mykey="your-open-ai-api-key",
+    path_in="images",
+    captions_file="captions_file.csv",
+    model="gpt-4o-mini"
+)
+```
+
+---
+
+### License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+### Contributing
+
+We welcome contributions! If you'd like to contribute:
+
+1. Fork the repository
+2. Create a feature branch:
+
+```bash
+git checkout -b feature-name
+```
+
+3. Commit your changes:
+
+```bash
+git commit -m "Add new feature"
+```
+
+4. Push to the branch:
+
+```bash
+git push origin feature-name
+```
+
+5. Open a pull request
+
+---
+
+For a full research example using `vistopics`, see:  
+Lokmanoglu, A. D., & Walter, D. (2025, accepted). *Topic Modeling of Video and Image Data: A Visual Semantic Unsupervised Approach*. Communication Methods and Measures. [Replication Code on GitHub](https://github.com/aysedeniz09/VisTopics/tree/main/paper)
+
+
+---
+
+### Contact
+
+If you have any questions or feedback, feel free to contact:
+
+**Ayse Lokmanoglu** & **Dror Walter**
+GitHub: https://github.com/aysedeniz09/VisTopics
+
+---
+
+### Acknowledgments
+
+- OpenAI for providing APIs used in the captioning feature, and for Researcher Access Program
+- FastDup for efficient duplicate detection
+- OpenCV for video and image processing utilities

vistopics-0.1.7/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"

vistopics-0.1.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vistopics-0.1.7/setup.py

@@ -0,0 +1,36 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="vistopics",
+    version="0.1.7",
+    description="A package for video and image processing with captioning capabilities",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="Ayse D. Lokmanoglu & Dror Walter",
+    author_email="alokman@bu.edu",
+    url="https://github.com/aysedeniz09/VisTopics",
+    license="MIT",
+    packages=find_packages(),
+    install_requires=[
+        "openai>=1.50.0",
+        "opencv-python>=4.9.0,<4.10",
+        "opencv-python-headless>=4.9.0,<4.10",
+        "pandas>=2.0.3,<2.2",
+        "requests>=2.28.0",
+        "yt-dlp>=2024.12.6",
+        "gradio>=3.36.0",
+        "aiofiles>=23.0",
+        "pydantic>=2.8",
+        "urllib3>=1.26",
+        "beautifulsoup4>=4.12"
+    ],
+    extras_require={
+        "fastdup": ["fastdup>=2.15", "numpy~=1.23.0"]
+    },
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.9",
+)

vistopics-0.1.7/vistopics/__init__.py

@@ -0,0 +1,6 @@
+from .captioning import *
+from .extract_frames import *
+from .reduce_frame import *
+from .video_scrape import *
+from .image_download import *
+

vistopics-0.1.7/vistopics/captioning.py

@@ -0,0 +1,124 @@
+def encode_image(image_path):
+    import base64
+    with open(image_path, "rb") as image_file:
+        return base64.b64encode(image_file.read()).decode('utf-8')
+
+
+def get_caption_main_func(base64_image, api_key, model):
+    """
+    Generates a caption for a single image using the specified model and API key.
+
+    Args:
+        base64_image (str): Base64-encoded string of the image.
+        api_key (str): API key for OpenAI.
+        model (str): Model to use for caption generation (e.g., 'gpt-4', 'gpt-3.5-turbo').
+
+    Returns:
+        str: Generated caption or an error message.
+    """
+    import requests
+
+    custom_prompt = (
+        "Directly describe with brevity and as brief as possible the scene or characters without any introductory "
+        "phrase like 'This image shows', 'In the scene', 'This image depicts' or similar phrases. If there is a text in "
+        "the image mention there is a text but do not caption the text, just start describing the scene please. If you "
+        "recognize historical figures and current celebrities and politicians in the picture give their full name, but "
+        "don't give the whole background about who they are"
+    )
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key}"
+    }
+    payload = {
+        "model": model,  # Dynamic model parameter
+        "messages": [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": custom_prompt},
+                    {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}}
+                ]
+            }
+        ],
+        "max_tokens": 300
+    }
+
+    try:
+        response = requests.post("https://api.openai.com/v1/chat/completions", headers=headers, json=payload)
+        response.raise_for_status()
+        response_json = response.json()
+
+        if 'choices' in response_json and response_json['choices'] and 'message' in response_json['choices'][0]:
+            caption = response_json['choices'][0]['message'].get('content', 'Caption not found').strip()
+            return caption
+    except requests.RequestException as e:
+        print(f"API request failed: {e}")
+    return "Failed to get caption"
+
+
+def list_files(folder):
+    """
+    Lists all files in the specified folder and subdirectories.
+
+    Args:
+        folder (str): Path to the folder.
+
+    Returns:
+        list: List of file paths.
+    """
+    import os
+    file_list = []
+    for root, dirs, files in os.walk(folder):
+        for file in files:
+            file_list.append(os.path.join(root, file))
+    return file_list
+
+
+def get_caption(mykey, path_in, captions_file, model):
+    """
+    Generates captions for images and saves them to a CSV file.
+
+    Args:
+        mykey (str): API key for the captioning service.
+        path_in (str): Directory containing images to process.
+        captions_file (str): Path to the CSV file to save captions.
+        model (str): Model to use for caption generation (e.g., 'gpt-4', 'gpt-3.5-turbo').
+    """
+    import csv
+    import os
+    import pandas as pd
+    import random
+    import time
+
+    # List all images in the input directory
+    all_images = list_files(path_in)
+
+    # Load existing captions if the file exists
+    try:
+        df = pd.read_csv(captions_file)
+        existing_images = df['image_path'].tolist()
+    except FileNotFoundError:
+        existing_images = []
+
+    # Filter out images that already have captions
+    new_images = [img for img in all_images if img not in existing_images]
+
+    # Open the captions file for appending
+    with open(captions_file, mode='a', newline='') as file:
+        writer = csv.writer(file)
+
+        # Write header if the file is new
+        if not existing_images:
+            writer.writerow(['image_path', 'caption'])
+
+        # Process each new image
+        for i, img_path in enumerate(new_images):
+            print(f"Processing image: {img_path}")
+            time.sleep(random.uniform(1, 5))  # Random delay to avoid API rate limits
+            base64_image = encode_image(img_path)
+            caption = get_caption_main_func(base64_image, mykey, model)
+
+            # Write the current row to the CSV file
+            writer.writerow([img_path, caption])
+            file.flush()  # Ensure data is written to disk
+            print(f"Caption done for image {i + 1}/{len(new_images)}")