User Manual

1. Introduction

Welcome to the official user manual for Texture Ripper, your all-in-one solution for extracting, processing, and preparing PBR materials. Designed for game developers, technical artists, and 3D professionals, this tool streamlines the entire texturing pipeline, from a single source image to a full set of game-ready maps. Its non-destructive workflow ensures your original images are never modified, while powerful project files keep track of every point, setting, and adjustment you make. This manual will guide you through all the features and workflows to help you get the most out of the application.

2. The Welcome Window: Your Hub

The Welcome Window is your mission control for managing projects. It appears on startup and can be accessed anytime via the Home button (H) on the main toolbar. It's designed to help you get into your work quickly and stay organized.

Sidebar & Navigation

The left sidebar provides access to the main sections and actions.

• PROJECTS: This is your complete library of every project you have ever saved or loaded. Unlike a simple "recent files" list, this view tracks projects regardless of where they are saved on your computer, providing a true central hub for all your work.
• UPDATES: Displays the latest release notes and changelogs for the application, so you can stay up-to-date with new features, improvements, and fixes.
• TRASH: A safe place for deleted projects. Instead of being permanently erased, projects you move to the trash are stored here. You can right-click any item in the trash to Restore it to your main projects list or Delete it Permanently.
• New scene: Closes the Welcome Window and opens a fresh, blank canvas in the main application.
• Load Project: Opens a file dialog to browse your computer and load any .json project file. This also automatically adds the project to your main project list.

Project Management

• Opening a Project: Simply click on any project card to load it.
• Project Context Menu: Right-click on a project card to open a context menu with more options:
  • Rename Project: Allows you to change the name of the project file.
  • Move to Trash: Safely moves the project and its associated files to the Trash folder.

3. The Main Interface

The UI is composed of a central Canvas surrounded by several dockable panels. You can click and drag the title bar of any panel to undock it into a floating window or rearrange it on the screen to create your perfect workspace layout. Your layout is saved automatically when you close the application.

1. Canvas: The main workspace where your source image is displayed and where you create and manipulate crop regions with draggable points.
2. Layers Panel (L): A hierarchical list of all your crop regions (layers) and folders. You can select, rename (F2), delete (Del), duplicate (Ctrl+D), and organize your crops here.
3. 2D Preview: Shows a real-time, perspective-corrected preview of the texture extracted from the currently selected crop region. A floating toolbar at the bottom of this panel lets you switch between viewing the Albedo, Normal, AO, and other generated maps.
4. Atlas Preview: Shows a real-time preview of the final texture atlas, combining all your defined crop regions into a single, tightly packed image.
5. 3D Preview: A high-fidelity PBR renderer that provides a live 3D preview of the currently selected crop's material. This is the ultimate tool for validating your material under realistic lighting conditions.
6. PBR Editor (E): The control center for tweaking all PBR map generation settings. This panel is dynamically updated to show collapsible sections with detailed controls for each map type.
7. Main Toolbar: Contains buttons and menus for the most common actions, from managing projects to adding layers and exporting your finished textures.

4. Core Workflow: Your First Texture

Step 1: Start a New Project & Import an Image

Every great material starts with a source image. You have several convenient ways to bring one into Texture Ripper:

• Import Button: Click the Import Image(s) button (Ctrl+O) on the main toolbar to open one or more image files. If you select multiple images, they will be automatically packed onto a single, large canvas for you.
• Drag and Drop: Simply drag image files from your desktop or file explorer directly onto the canvas.
• Paste from Clipboard: Copy an image to your clipboard from anywhere and use the Paste Image button (Ctrl+V) on the main toolbar.

Step 2: Create and Position a Crop Region

A "Crop Region" (or "Layer") is a four-pointed polygon that defines the area of the image you want to extract.

• Click the Add New Crop Region button (C) on the toolbar. A new layer will appear in the Layers Panel.
• With the new layer selected, click four points on the canvas to define the corners of the texture you want to extract. The 2D and 3D Previews will instantly update to show your perspective-corrected texture.

Step 3: Refine the Region & PBR Maps

Now, fine-tune your selection and material properties.

• Move a Point: Click and drag any of the four corner points to precisely match the texture's shape. Use the built-in snapping to align points perfectly to image edges.
• Move the Polygon: Click and drag the polygon itself to move all four points at once.
• Adjust PBR Maps: Press E to open the PBR Editor. Select a preset or adjust the sliders for the Normal map, Roughness, etc., and see the results update instantly in the 2D and 3D Previews.

Step 4: Export Your Textures

Once you're happy with your material, click the Export button on the toolbar to open the Export Dialog.

• Export Selected Crop (Ctrl+E): Saves the currently selected region and its generated PBR maps.
• Export All Crops (Alt+E): Saves every region in your project as an individual set of textures.
• Export Atlas (Shift+E): Saves the tightly packed texture atlas and its corresponding PBR maps.

5. Advanced Features & Techniques

The Canvas: Your Workspace

The Canvas is an interactive space with several tools to make your workflow efficient. The view's zoom and pan controls also impact the size of the draggable points, ensuring they are always visible and easy to click regardless of your zoom level.

• Navigation: Middle-click and drag to pan the view. Use the Mouse Wheel to zoom in and out, centered on your cursor's position.
• Creating Shapes: Right-click on the Canvas and select Add Shape to quickly create a predefined Square, Rectangle, or a Fullscreen region. The dimensions for these default shapes can be set in the `Settings` dialog.
• Grid and Snapping (G): Press G to toggle a grid overlay inside your polygons for better visual alignment. Points automatically snap to image edges and to the grid. The `Grid Size` and `Snap Tolerance` are fully customizable in `Settings`.
• Aligning Points (Q): Select two or more points by holding Shift and clicking them. Press Q to automatically align them either horizontally or vertically. This is essential for creating perfect rectangles quickly.
• Crop Only Mode: Right-click a polygon and check Crop Only. This disables the perspective-correction warp and performs a simple rectangular crop. This mode is ideal for extracting flat, non-perspective textures like UI elements, decals, or sprites.
• Tweak Aspect Ratio: Right-click on a polygon and select `Tweak Aspect Ratio` to enable special handles. Dragging these handles performs a non-destructive transformation, stretching or compressing the final texture to correct for lens distortion or alter proportions without moving the original corner points. Your tweaks are saved with the project and are part of the undo/redo stack.
• Undo/Redo: Every action, from moving a point to changing a PBR setting, is recorded. Use Ctrl+Z to Undo and Ctrl+Y to Redo your actions.

The PBR Editor (E)

The PBR Editor is the heart of the material creation process. Each map type has its own collapsible section with a "Reset" button. The application includes a range of presets for common material types, which are a great starting point for your own projects. All PBR map generation is performed in a non-destructive, 16-bit color depth where applicable to preserve the maximum possible detail.

Albedo (Base Color)

• Delight Texture: This advanced feature removes shadows and uneven lighting from your source photo, resulting in a flat, neutral-lit base color. Think of it as digitally "relighting" the image to remove photographic flaws.
• Contrast Equalization: Automatically stretches the image histogram to improve overall contrast. You can use a global method or a more intelligent local method (CLAHE) that brings out subtle details in specific areas without washing out the entire texture.
• Color Vibrance & Saturation: Use Vibrance to intelligently boost muted colors without over-saturating already vibrant ones. Use Saturation to uniformly adjust the intensity of all colors.

Normal (Surface Detail)

• Overall Strength: This slider controls the intensity of the bumps and grooves, making them more or less pronounced.
• Invert Y Axis: Different game engines (like Unreal and Unity) expect the green channel of a normal map to be oriented differently. This checkbox allows you to flip the orientation to match your target engine's standard.
• Base/Mid/Fine Detail Influence: These three sliders are the core of the multi-frequency algorithm. They give you complete artistic control to separately adjust the contribution of large, low-frequency shapes (Base), medium-sized bumps and features (Mid), and tiny surface imperfections (Fine).

Displacement (Height)

The Displacement map is a grayscale image used to create real geometric detail on your mesh through tessellation in the 3D Preview or in your game engine. White areas represent high points, and black areas represent low points.

• Overall Height Scale: Controls the physical height of the displacement in the 3D preview.
• Apply Height Curve: Applies a non-linear contrast curve to the map, allowing you to push the high and low values further apart for more dramatic height differences.
• Micro-Detail Strength & Surface Grain: These sliders allow you to add fine, procedural details to the surface, such as small pits, scratches, or a general grainy texture, making the material feel more realistic.

Ambient Occlusion (AO)

• Overall Softness: Adjusts the size of the contact shadows. A low value gives sharp, gritty shadows, while a high value produces soft, diffused results.
• Preserve Edges: Uses an advanced edge-preserving blur method to maintain sharper transitions at object boundaries, preventing a blurry or muddy look.
• Cavity Intensity: This slider specifically targets cracks and crevices, adding a detailed cavity map to emphasize recessed areas and add grime.

Roughness (Microsurface)

The Roughness map controls how light scatters across the surface. A value of 0 (black) creates a smooth, mirror-like surface, while `1` (white) makes the surface completely matte (like chalk).

• Overall Roughness Level: Globally brightens or darkens the map, making the entire surface appear more or less rough.
• Contrast Curve: A powerful tool that applies an S-curve to the values. This allows you to create high-contrast roughness maps that make raised areas shinier and recessed areas rougher (or vice-versa), crucial for realistic wear and tear.
• Micro/Macro Detail Impact: Control how fine imperfections (Micro) and larger structural details (Macro) affect the overall roughness.

Metallic

The Metallic map is a black-and-white mask that defines if a surface is a metal (`1.0`, white) or a non-metal (`0.0`, black). The engine uses a combination of luminance, color saturation, and edge detection to generate this map.

• Threshold: Sets the cutoff point for what is considered metallic. Pixels above this value are more likely to be included in the mask.
• Grayscale Influence: This slider blends a luminance-based mask with a color-based mask. Higher values prioritize the shape and brightness of the image, which is useful for identifying metallic objects that aren't a specific color.

Emission (Glow)

• Enable Emission: A simple checkbox to toggle the effect on or off.
• Mode: You can choose `Color From Albedo` (the glowing areas take their color from the base albedo map) or `Mask Only` (a pure grayscale mask is created).
• Brightness Threshold: Sets a cutoff point; any pixel brighter than this value will begin to glow.
• Glow Radius & Strength: Control the size, softness, and overall intensity of the glow bloom effect.

Tiling (Experimental)

• Enable Tiling: Toggles the feature on and off for all generated maps. When enabled, Texture Ripper analyzes your texture and intelligently finds the least noticeable path to create a seamless, tileable material.
• Show Seams: Displays the path of the generated seam as a vibrant, glowing overlay in the 2D and 3D previews.
• Seam Falloff: Controls the width and feathering of the blending area along the seam path, allowing you to create a softer or sharper transition.

The 3D Preview: Real-Time Material Validation

The 3D Preview is a core feature for evaluating your materials. Its high-fidelity, PBR-correct renderer provides accurate, real-time feedback on how your textures will look and behave in a real-world lighting environment. It is controlled by a powerful yet intuitive floating toolbar that appears at the bottom of the panel, giving you full control over the mesh, lighting, and camera.

Navigation & Interaction

The camera and lighting controls are designed to be fluid and direct. Note that these manual controls are paused when Showcase Mode is active, unless you are holding down a mouse button to temporarily take control.

• Rotate Camera/Mesh: Left-click and drag to rotate the camera around the object. This rotates the camera in Plane mode, and the mesh itself in Sphere or Rounded Cube mode.
• Rotate Light: Right-click and drag to change the angle of the main directional light source, allowing you to see how shadows and highlights play across your material's surface.
• Rotate IBL Environment: Hold Shift + Right-click and drag to rotate the Image-Based Lighting environment. This is crucial for checking how reflections and ambient light from the environment interact with your material.
• Pan: Hold the Middle Mouse Button and drag to move the camera horizontally and vertically without changing its rotation.
• Zoom: Use the Mouse Wheel to zoom in and out, getting a closer look at fine details or a wider view of the overall material.

The Floating Toolbar

The floating toolbar is your command center for the 3D Preview. Each button opens a dedicated pop-up panel with detailed settings, allowing you to customize every aspect of the preview environment.

• Camera: This panel controls the virtual camera.
  • Field of View (FOV): Adjusts the camera's lens, from a wide-angle view (low values) to a more zoomed-in, telephoto look (high values).
  • Reset Camera View: Instantly snaps the camera, zoom, and pan back to the default position for the currently selected mesh.
• Display: Controls how your material is rendered and displayed.
  • Tiling: Sets how many times the texture repeats across the surface of the mesh (Sphere and Rounded Cube only). This is essential for checking the quality of your seamless tiling.
  • Map Toggles: A series of checkboxes that allow you to disable individual PBR maps. This is an invaluable debugging tool for isolating problems. For example, if your material looks wrong, you can uncheck the "Normal" map to see if the issue lies with the base color or the surface detail.
  • Showcase Mode: An automated animation sequence that smoothly rotates the mesh, the primary light, and the IBL environment. This is perfect for creating videos or GIFs to showcase your finished material from every possible angle. User interaction (like clicking the mouse) will temporarily pause the animation.
  • Debug Output: A dropdown menu that switches the renderer to display a single data channel instead of the final PBR result. You can view the raw UV Coords, the final Fresnel effect, or the contribution of the IBL Diffuse and Specular lighting. This is an advanced tool for technical artists to deeply analyze their material's properties.
• Mesh: Controls the 3D object your material is applied to.
  • Shape: Instantly switch between a Plane, Sphere, or Rounded Cube. The Plane will automatically resize to match the aspect ratio of your texture, making it perfect for viewing non-square materials. The Sphere and Rounded Cube are ideal for checking for seams and how the material behaves on curved surfaces.
  • Material: Toggles the base reflectivity of the mesh between Matte (like plastic or clay) and Shiny (like a polished surface). This affects how the Fresnel effect is calculated.
  • Resolution: Controls the polygon density of the mesh. A higher resolution provides more geometry, which is essential for seeing fine detail when using Tessellation and Displacement.
  • Toggle Wireframe: Renders the mesh as a wireframe, allowing you to see the underlying geometry and the effect of tessellation.
• Displacement: Controls real, geometric displacement of the mesh surface.
  • Enable Displacement: This master toggle turns on Tessellation, a powerful GPU feature that dynamically adds new polygons to the mesh based on your camera's distance.
  • Tessellation: Controls the quality and density of the new geometry created by tessellation. Higher values result in smoother, more detailed displacement at the cost of performance.
  • Height Scale: Adjusts the intensity of the displacement effect, pushing the high points of your Displacement map further out and pulling the low points further in.
• Lighting: Gives you full control over the scene's lighting.
  • Environment (IBL): Select an Image-Based Lighting environment from a list of presets captured from real-world locations (Studio, Overcast, Sunset, etc.). This is the most effective way to see how your material will look in different lighting scenarios. You can also load your own custom .hdr environment maps.
  • Show Background: Toggles the visibility of the IBL environment map in the background.
  • BG Blur: Adjusts the blurriness of the background image, allowing you to create a depth-of-field effect.
  • IBL Strength & Exposure: These sliders control the brightness. IBL Strength adjusts the intensity of the light coming from the environment map, while Exposure acts like a final camera exposure control for the entire scene.
  • Emission Strength: A global multiplier for the brightness of any glowing parts of your material defined by the Emission map.
  • Set Light Color: Opens a color picker to change the color of the main directional light source.
• Reset All: A master reset button that instantly restores every single setting in the 3D Preview—camera, lighting, mesh, and display—back to their original default values.

Exporting: Finalizing Your Assets

The Export Dialog is the final and most crucial step in the Texture Ripper workflow, allowing you to package your procedurally generated materials into industry-standard file formats. This dialog provides a host of powerful options to control the style, format, and optimization of your textures, ensuring they are perfectly tailored for your target game engine or rendering application. The "Information" panel at the bottom provides a convenient, real-time estimate of the final output resolution based on your current settings.

Upscaling & Style

This section allows you to define the final resolution and aesthetic of your exported textures before they are saved.

• Standard Upscale: A high-quality conventional resizing method (Lanczos interpolation) that allows you to scale your textures from 1x to 8x their extracted size. This is a fast and effective way to increase resolution for general purposes.
• Use AI Upscale: This powerful feature utilizes the Real-ESRGAN neural network to perform a 4x upscale. Unlike standard resizing which can blur details, AI Upscaling intelligently reconstructs and adds new, plausible detail, resulting in a significantly sharper and cleaner image. This feature is available for Free users (with a watermark) and is unlimited for Pro/Teams users.
• Retro Textures: This option creates a stylized, pixelated look reminiscent of classic 32-bit era games. It works by downscaling the texture using nearest-neighbor interpolation, which preserves sharp pixel edges, perfectly capturing a "PSX-like" retro aesthetic.

Additional Outputs

Here you can choose to generate supplementary files and apply common game engine optimizations.

• Generate PBR Textures: This is the master toggle for exporting all the PBR maps (Normal, Roughness, etc.) you've configured in the PBR Editor. If this is unchecked, only the base Albedo/Diffuse map will be exported.
• Use ORM Packing: A critical optimization for modern game development. When checked, Texture Ripper will combine three separate grayscale maps into a single RGB image. This technique, known as channel packing, dramatically reduces memory usage and improves performance in game engines. The standard packing order is:
  • Red Channel = Ambient Occlusion
  • Green Channel = Roughness
  • Blue Channel = Metallic
• Generate Color Palette: When checked, the application will analyze the dominant colors of your final Albedo map and generate a separate, beautifully formatted image swatch. This is perfect for artists and designers who need to establish a consistent color scheme for their project.

Output Format & Options

This section gives you precise control over the technical specifications of your output files to match any production pipeline.

• Naming Convention: To streamline the import process into game engines, you can choose a standard file suffix convention. Options for Unreal Engine (e.g., _D, _N, _ORM) and Unity (e.g., _Albedo, _Normal) are available.
• File Format: Select the best file format for your needs.
  • PNG: Lossless format with excellent alpha channel support. The best choice for most Albedo and mask textures.
  • JPEG: Lossy format with small file sizes. Good for reference images, but not recommended for high-precision maps like Normals or Displacement.
  • TGA (Targa): An older, lossless format still common in many game development pipelines.
  • TIFF: The best choice for high-quality data maps. It supports 16-bit color depth, which is essential for smooth gradients in Normal and Displacement maps, preventing visual artifacts like banding.
  • HDR: A 32-bit floating-point format capable of storing high dynamic range lighting information. Primarily used for creating custom IBL environment maps.
• Pad to Power-of-Two: Some game engines or rendering techniques require textures to have dimensions that are a power of two (e.g., 256, 512, 1024). This option will automatically pad your exported image with transparency to meet the next largest power-of-two dimension.
• Limit Max Size: This allows you to set a maximum resolution for your exported textures. Your plan determines the highest value you can choose (1024px for Free, 4096px for Indie), but you can always enter a smaller value. This is extremely useful for creating lower-resolution texture variants for LODs (Level of Detail) or for targeting less powerful hardware.

6. Keyboard Shortcuts

Action	Shortcut
Project & File
New Project	Ctrl + N
Load Project	Ctrl + L
Load Last Session	Alt + L
Save Project	Ctrl + S
Import Image(s)	Ctrl + O
Paste Image	Ctrl + V
Editing & Layers
Add Crop Region	C
Delete Selected Region	Del / Shift + C
Duplicate Selected Region	Ctrl + D
Rename Selected Region	F2
Align Selected Points	Q
Undo	Ctrl + Z
Redo	Ctrl + Y
View & Previews
Focus on Selection	F
Toggle Crop Grid	G
Toggle Live PBR Updates	R
Open PBR Editor	E
Exporting
Export Selected Crop	Ctrl + E
Export All Crops	Alt + E
Export Atlas	Shift + E
Application
Open Settings	Alt + S
Open Home Menu	H
Open Manual	F1