Texture Ripper v1.0 - User Manual

📖 Introduction

Welcome to GRIEFS Texture Ripper!

This application is a powerful, specialized tool designed for the modern texturing artist. Whether you are a game developer, technical artist, 3D modeler, or a modder bringing new life to classic games, Texture Ripper is built to streamline and accelerate a critical part of your workflow: capturing real-world or digital textures and preparing them for production.

Its primary purpose is to help you "rip," or extract, specific sections from a source image and transform them into perfectly clean, usable assets.

In standard workflows, this process can be tedious. Correcting perspective distortion in a typical photo editor is often a manual, time-consuming task, and organizing dozens of cropped textures is prone to error. Texture Ripper solves this by providing a dedicated environment for defining precise polygonal areas, automatically correcting for perspective, and exporting them as individual textures or into a highly optimized "Texture Atlas."

To further enhance your pipeline, the app includes advanced features like AI-powered upscaling and automatic PBR (Physically-Based Rendering) map generation.

This manual will guide you through every feature of the application, from your very first project to advanced professional workflows, empowering you to turn any image into a production-ready texture with speed and precision.

Getting Started

2.1. The Main Interface

When you first open Texture Ripper, you'll be greeted by the main interface. It's a clean, functional layout composed of several key areas designed for an efficient, non-distracting workflow.

The Canvas

This is your main interactive workspace. As a pannable and zoomable view, it's where you will load your source images, draw your crop regions, and meticulously manipulate their points.

All direct interaction with your texture sources happens here.

The Outliner

This panel on the right lists all the "Crop Regions" you've created, functioning like a layers panel in a standard graphics editor. It is the heart of your project's organization.

From here, you can select, rename, reorder, duplicate, and delete regions. Keeping your Outliner organized with clear names is key to an efficient workflow.

The Preview Docks

Located below the Outliner, these two panels provide essential, real-time feedback, eliminating guesswork.

Crop Preview:

This shows a live, perspective-corrected preview of the texture extracted from the currently selected region. As you adjust the points on the canvas, you will see the "un-warped" result here instantly.

Atlas Preview:

This shows a live preview of what your final combined texture atlas will look like. It updates as you add, remove, or modify regions, giving you a clear picture of your final output at all times.

The Toolbar

Located at the bottom of the window, this bar contains all the primary tools and actions. It provides quick access to project management (New, Save, Load), image import, creating and managing crop regions, and exporting your final work.

2.2. Core Concepts

Understanding these three core concepts is essential to mastering Texture Ripper.

Project

A project is saved as a .json file, which acts as the "brain" for your entire session. It doesn't store the images themselves but rather contains references to your source image(s) and, crucially, all the data about your crop regions — their precise point coordinates, names, and settings.

This approach makes for a non-destructive workflow, meaning your original image files are never altered. You can always return to your project to make adjustments.

Crop Region

This is a polygonal shape (typically a 4-point quad) that you draw on the canvas to define the exact area of the image you want to extract.

Each region is an independent object treated as a separate layer in the Outliner. The power of the region tool is its ability to perform perspective transformation. By placing the four points at the corners of a distorted surface (like a wall viewed from an angle), the tool mathematically "un-warps" it into a perfectly flat, square-on texture.

Texture Atlas

A single, larger image that combines all your individual cropped textures using an efficient packing algorithm. In game development, minimizing the number of individual texture files is critical for performance.

Each texture requires a separate "draw call" from the graphics card. By packing many textures into a single atlas, you reduce hundreds of potential draw calls to just one, leading to significantly faster loading times and smoother frame rates.

Texture Ripper's atlas tool automates this packing process for you.

Your First Project: Step-by-Step

Let's walk through a typical workflow from start to finish to see how these concepts come together in practice.

🔹 Step 1: Create a New Project

While you can start working immediately, it's best practice to first create a project file. This establishes the file path for your work and enables features like autosave to function correctly.

• Click the 📄 Project button on the toolbar.
• Select 🆕 New Project (or press Ctrl+N).
• You will be prompted to enter a name for your project. This will create a .json file in your default project directory (Pictures/Texture Ripper/projects), ready to save your progress.

🔹 Step 2: Import an Image

You have several flexible ways to bring an image into the canvas, catering to different workflows.

• Import File: Click the 🖼️ Import Images button (Ctrl+O). This is the most powerful method for batch work, as you can select one or multiple images. If you select multiple, the app will automatically arrange them into a single, large composite canvas for you.
• Drag and Drop: For a quick start, simply drag image files from your computer's file explorer directly onto the canvas.
• Paste from Clipboard: A great option for spontaneous work. Copy an image from anywhere (a web browser, another image editor) and press the 📋 Paste Image button (Ctrl+V) on the toolbar to place it directly on the canvas.

🔹 Step 3: Create a Crop Region

Now, let's define the texture we want to rip. This is the core interactive step.

• Click the ➕ Add Crop Layer button (C) on the toolbar. A new item will appear in the Outliner panel, named "1". This is now your active layer.
• Move your mouse over the canvas. Your cursor is now ready to define the vertices of your polygon.
• Click four times on the canvas around the object you want to extract. For best results, click the four corners of the texture area in a clockwise or counter-clockwise order. As you click, a translucent polygon will form, showing your selection area.
• Upon placing the fourth point, the polygon becomes a Crop Region. You'll immediately see the extracted, perspective-corrected texture appear in the Crop Preview dock.

🔹 Step 4: Edit the Crop Region

Achieving a perfect extraction requires precision. The application gives you full, precise control over the shape of your region.

• Move Points: Click and drag any of the purple corner points to adjust the shape. Notice how the Crop Preview updates in real-time, showing the "un-warping" effect.
• Move the Whole Region: To reposition your selection without changing its shape, click and drag the polygon itself (not the corner points).
• Snapping: For pixel-perfect accuracy, the points will automatically snap to the edges of the source image or to the background grid (if enabled). You can configure the snapping distance, or "tolerance," in the Settings menu.
• Focus: In a large project with many regions, it's easy to lose track of your selection. Simply press the F key to automatically zoom the canvas to fit the currently active region.

🔹 Step 5: Use the Outliner (Layer List)

The Outliner is your command center for managing multiple crop regions.

• Select a Region: Simply click on an item in the list to make it the active region on the canvas.
• Rename a Region: A crucial organizational step. Press F2 while a layer is selected, or right-click it, to give it a meaningful name (e.g., "Brick Wall", "Door Panel"). This name will be used as the default filename on export, saving you time later.
• Delete a Region: Select a layer and press the Delete key or the 🗑️ Clear Points button (Shift+C) to remove it from your project.
• Duplicate a Region: Press Ctrl+D to create an identical copy of the selected region. This is extremely useful for ripping many similar elements, like windows on a building or panels on a sci-fi wall.

🔹 Step 6: Export Your Textures

This is the final step, where your carefully defined regions become tangible assets.

• Click the 📦 Export button on the toolbar to open the export menu.
• Choose one of the powerful export options:
  • 💾 Export Selected Crop (Ctrl+E): Exports only the currently selected region as a single image. Perfect for testing a single texture.
  • 📁 Export All Crops (Alt+E): A batch function that exports every defined region as a separate, named image file into a folder you choose.
  • 🧩 Export Atlas (Shift+E): The core production feature. This combines all your regions into a single, efficiently packed texture atlas.
  • 📚 Export All (Shift+Alt+E): The ultimate time-saving workflow option. It performs both of the above actions at once: it saves all individual crops and the texture atlas into a single, neatly organized folder named after your project.
• After selecting an option, an Export Options dialog will appear, which is covered in detail in the next section.

Advanced Features & Export Options

4.1. The Export Dialog

This dialog gives you powerful, granular control over the final output of your textures, allowing you to tailor them for any use case.

Upscale Factor: Choose a numerical multiplier to increase the resolution of your exported textures. This uses a high-quality Lanczos resizing algorithm, which is excellent for producing sharp, clean results without the artifacts of simpler methods.

Use AI Upscale (alpha): This is the most advanced feature for resolution enhancement. It uses a pre-trained neural network called Real-ESRGAN to intelligently upscale your texture by 4x. Unlike traditional resizing, it can generate new, plausible details, making it perfect for creating high-resolution assets from low-resolution sources or for restoring detail in old game textures. Be aware that this process is computationally intensive and will take significantly longer.

Generate PBR Textures: When checked, the application will automatically analyze your source image and generate a full set of Physically-Based Rendering (PBR) maps alongside your main color texture. This is a massive time-saver for 3D artists. See the PBR section below for a full explanation.

Pad to Power-of-Two Dimensions (Atlas only): For optimal performance and memory management, game engines prefer textures with dimensions that are a power of two (e.g., 512x512, 1024x1024, 2048x2048). This option will automatically pad your atlas with empty space to meet the nearest power-of-two size, ensuring maximum compatibility and performance, especially when generating mipmaps.

Retro Textures: This mode is specifically for creating a "PlayStation 1" or "Nintendo 64" aesthetic. It disables all upscaling and resizes your textures to a small resolution (e.g., 96x96) using "nearest neighbor" interpolation. This method doesn't blend pixels, preserving the sharp, blocky look that defines that generation of games.

4.2. PBR Map Generation Explained

Physically-Based Rendering (PBR) is the industry standard for creating realistic, consistent materials in modern graphics. If you check Generate PBR Textures during export, the application will intelligently analyze your source image and create the following essential data maps, saved as grayscale or color images:

• _N (Normal Map): What it does: Adds fake surface detail. This purple-ish map tells the game engine how light should bounce off the microscopic details of a surface. Why it's important: It creates the illusion of complex geometry like bumps, cracks, pores, and grooves without adding any actual polygons to your model, keeping performance high while achieving incredible visual fidelity.
• _AO (Ambient Occlusion): What it does: Simulates soft, contact shadows. This grayscale map darkens areas where objects meet or where ambient light from the environment would be blocked, such as in crevices or under ledges. Why it's important: AO adds a powerful sense of depth and realism, grounding objects in the scene and making surface details "pop."
• _Rough (Roughness Map): What it does: Controls the shininess or glossiness of a surface. This grayscale map defines how light scatters when it hits the surface. Why it's important: A white value indicates a very rough surface (like concrete or terracotta) that scatters light widely, resulting in a matte appearance. A black value indicates a perfectly smooth surface (like polished plastic or calm water) that reflects light clearly.
• _Metal (Metallic Map): What it does: Defines the "metalness" of a surface. This is typically a black-and-white map that tells the engine's shading model how to treat the material. Why it's important: A white value indicates the surface is a raw metal, causing it to reflect light and take its color from reflections. A black value indicates it is a non-metal (a "dielectric"), causing it to have its own base color and reflect light less strongly.

4.3. Image Adjustments

You can perform non-destructive adjustments to your source image for the entire project. This is useful for correcting exposure or color balance before you even start ripping. Right-click on an empty area of the canvas and select ⚙ Adjust Image. This opens a dialog where you can change:

• Exposure, Brightness, Contrast
• Saturation, Highlights, Shadows
• Sharpening

These changes are stored in your project file and only affect the image within the app and on export; your original source file is never modified. You can reopen the dialog at any time to tweak the settings.

4.4. Advanced Region Controls (Right-Click Menu)

Right-click on a polygon in the canvas to access a context menu with these powerful options:

• 🔪 Crop Only: By default, the app performs a perspective transformation. However, if you are working with a flat image like a sprite sheet or a top-down texture, you don't need this. Enabling "Crop Only" will simply cut out the rectangular bounding box around your polygon without any distortion. The polygon will turn red to indicate this mode is active.
• 🪟 Show Grid: Toggles a perspective-correct grid inside the selected polygon. This is an invaluable visual aid, helping you to perfectly align your points and visualize how the surface is being "un-warped."
• 🔒 Lock Movement: In a complex project with many overlapping regions, it can be easy to accidentally move one. This option locks the selected region, preventing it and its points from being moved. The region will turn a solid blue-purple color, giving you a clear visual indicator that it is locked.

Pro-Tips and Workflow Strategies

• Batch Processing Mindset: When working with large, dense texture sheets (like those from an asset store or your own photos), import the entire sheet at once. Use the ➕ Add Crop Layer (C) and 🔁 Duplicate Layer (Ctrl+D) actions repeatedly to quickly define all the areas you need. Use the Outliner (F2) to rename them logically as you go (e.g., "stone_01", "stone_02"). This "assembly line" approach is incredibly efficient.
• Combine Manual and AI Upscaling: The AI upscale is powerful but slow. For a large project, a smart strategy is to do a standard 2x or 4x export of all your crops first. Then, identify the "hero" assets—the textures that will be seen up-close by the player—and re-export only those selected crops with the "Use AI Upscale" option checked. This gives you the best of both worlds: speed for general assets and maximum quality for important ones.
• Save Often, Undo/Redo Freely: Texture Ripper has a robust multi-level Undo/Redo system (Ctrl+Z / Ctrl+Y). Don't be afraid to experiment with point placement or image adjustments. Combined with regular project saving (Ctrl+S), you have a very safe and flexible workflow that encourages experimentation. Autosave is also there as a final safety net.
• Use Shapes for Quick Primitives: Don't forget you can right-click on an empty area of the canvas to access the "Add Shape" menu. This allows you to instantly create perfectly proportioned squares or rectangles, which you can then move and resize. This is significantly faster than placing four points manually for simple, non-distorted shapes.
• Optimize Performance on Large Projects: If the application feels sluggish while you're dragging points on a very high-resolution image (e.g., 8K or larger), press the 🧊 Realtime Preview toggle (R). This will temporarily disable the live preview updates, making point manipulation buttery smooth. The previews will instantly update once you stop moving the point. You can toggle it back on whenever you need the live feedback again.

Troubleshooting & FAQ

"Why is AI Upscale so slow?"

AI upscaling uses a complex neural network that requires a massive number of calculations, making it very demanding on your computer's processor. The time it takes is normal. It's a feature best reserved for your most important assets where visual quality is the absolute top priority.

"My atlas preview or crop preview is empty."

This usually happens for one of two reasons: 1) You haven't defined any crop regions yet, or 2) The currently selected region has fewer than 3 points, so it can't form a valid geometric shape to extract texture from. Ensure your active layer has at least 3, and ideally 4, points defined.

"The application is lagging when I move points."

This can happen with very high-resolution source images. The quickest solution is to press R to toggle off Realtime Preview. The interface will become much more responsive, and the previews will update once you release the mouse button. You can also lower the Max Preview Texture Size (UI) in the settings for a permanent performance boost on less powerful machines.

"I imported multiple large images and the app warned me they were scaled down."

To ensure stability and prevent crashes from using excessive memory, the canvas has a maximum dimension limit. If you import a collection of images that, when combined, would exceed this limit, the application will automatically scale them down to fit. This scaling only affects the canvas view for editing purposes; your exports will still be based on the full-resolution source data where possible.

"Can I edit a project after moving the source image file?"

The project .json file saves the absolute file path to your source image(s). If you move the image, the project won't be able to find it upon loading. For best results, keep your project files and their associated source images together in the same parent folder.

Reference Guide

7.1. Toolbar Actions

7.2. Other Important Shortcuts

7.3. The Settings Window (Alt+S)

• General Display: Control the visual size of points, lines, and fonts. You can also set Max Cropped Texture Size (Export) to cap export resolutions and Max Preview Texture Size (UI) to improve performance by generating smaller previews.
• Grid and Snapping: Adjust the size of the grid and how close points need to be to snap to it or to the image edges.
• Default Object Sizes: Set the default dimensions for the pre-made shape tools (Square, Vertical/Horizontal Rectangle) that can be added via the right-click context menu on the canvas.
• System and Paths: Enable or disable autosave, set the autosave interval, and change the default folder where projects are saved.

Thank you for using Texture Ripper! We hope it becomes an indispensable part of your creative toolkit. For tutorials and more information, visit the official website griefs.xyz