Welcome to the official technical manual for GRIEFS SURFACE (formerly GRIEFS TEXTURE RIPPER).
SURFACE is a standalone desktop application for generating PBR materials from images, designed for 3D artists and game developers. It allows you to extract regions from a source image, correct perspective distortion, and generate a full set of Physically Based Rendering (PBR) material maps from the result.
The workflow is non-destructive and includes tools for seamless tiling, AI upscaling, and real-time 3D preview.
This manual provides an exhaustive, component-level breakdown of all application behaviors, parameters, mathematical models, filter options, interface layers, keyboard shortcuts, and asset pipeline configuration grids. It is structured to serve as both an introductory walkthrough and a permanent pipeline reference.
[ NOTE ]: This manual assumes an understanding of standard real-time rendering pipelines, PBR channels (Albedo, Normal, Displacement, Ambient Occlusion, Roughness, Metallic), UV projection matrices, and image resizing interpolation methods.
Upon initialization, the Welcome Window (or Dashboard) acts as the centralized
system manager for license authorizations, external file indexing, changelog verification, and
project serialization. You can toggle this overlay at any point in the main workspace by pressing
H or selecting the Home icon from the toolbar.
WhatsNew): Communicates directly with the cloud
database to query and download the official system changelog feed. Update summaries are grouped
dynamically into categories (Features, Improvements, Fixes) with full version numbers and
release timestamps.Projects): The primary workspace library. Rather than
relying on fragile relative paths or standard OS "recent files" caches, SURFACE scans three
directories: your project folder (located in '%APPDATA%/GRIEFS SURFACE/projects' or
equivalent platform directory), a dedicated assets folder hosting pre-packaged demo projects,
and an external project cache tracking custom projects loaded or saved across network drives and
local mount points.Trash): A virtual holding cache preventing accidental
project loss. Moving a project to the trash isolates its workspace structure in a local
directory cache. You can restore the project card back to the active Projects library or
execute a permanent physical removal from the storage device.Learn): Loads an active list of instructional video
tutorials. Videos are presented as media cards with titles, descriptions, and thumbnail sheets.
Click interactions launch the corresponding URL directly in the system's default browser. Cache
directories store metadata ('youtube_videos.json') and thumbnails ('youtube_thumbnails/')
locally to allow offline indexing.About): Exposes active build metadata, keyboard shortcuts
and licensing statuses.Hovering over any project card in the grid highlights its boundary container. Right-clicking any active project card spawns a technical context menu offering the following operations:
Enter confirms the change.
.gsfp) from disk.The top-right corner of the Welcome Window hosts your account node. On web builds, this node communicates with the login system at to validate your credentials and manage account states.
The main workspace is structured as a dockable layout. Dock panels can be rearranged, resized, and separated into floating workspaces. The layout state is written to config on exit and restored on startup.
Ctrl+D),
or deleted (Delete).D key.The Canvas processes sub-pixel coordinate coordinates in double-precision floating-point format, allowing precise edits regardless of the source image resolution. Viewport pan and zoom matrices translate screen coordinates into world coordinates, dynamically scaling visual components (like vertex handles) so they remain easily interactive at any zoom factor.
F): Pressing F when no region is
selected adjusts the zoom and pan matrix to fit the entire source image bounds within the
visible canvas. If a region is selected, pressing F fits the camera zoom to the
bounding coordinates of that specific region.A suite of four tools controls canvas interactions, toggled via keyboard hotkeys or toolbar icons:
R): Click and drag to draw a rectangular region.
The start and end positions define the corners of the quadrilateral.C): Allows custom quadrilateral boundary
drawing. Click four distinct positions sequentially to place the corner handles. A blue dashed
line tracks the cursor from the last placed vertex to assist layout.M): The default
manipulation tool. Used to
click and drag individual corner handles, translate edge midpoints, or drag the interior of a
region to move its entire bounding shape without altering its corner geometry.T): Allows emplacing annotations on the canvas.
Click to spawn a text box, enter text strings, and customize font sizing, scale, color tint
(RGBA), background visibility, and position lock flags.S): Toggle with the S key. When
active, moving a corner vertex snaps it to the borders of the source image, to active grid
lines, or to matching horizontal/vertical coordinate baselines of other vertices.L): Toggle with the L key. Locking a
region freezes its vertices and transforms, preventing accidental mouse edits while allowing its
PBR parameters to be adjusted in the panel.U): Toggle with the U key. When
active, adjusting a vertex handle scales the entire region while preserving its aspect ratio.
Shift and click on regions in the canvas or
layers panel to build a selection list. You can translate, copy (Ctrl+C), duplicate
(Ctrl+D), delete (Delete), or batch-apply PBR settings to all selected
regions.When Tangent Warping is disabled, small white circular handles appear at the midpoints of the straight lines connecting the four corner vertices. Clicking and dragging a midpoint handle translates the corresponding edge parallel to its normal axis, keeping it straight. This allows shifting a single crop boundary (e.g., aligning it to a straight grout line or wall edge) without altering the positions of the other three corners.
Standard perspective correction maps a flat quadrilateral to a rectangle using a homography matrix, which assumes straight edges. However, real-world textures are often photographed on curved surfaces (like pillars, columns, vaulted ceilings, or creased fabric). To address this, SURFACE includes a Tangent Warp engine.
[ PIPELINE WARNING ]: Tangent warping uses GPU pixel shaders to perform non-linear warp calculations. Ensure your target region size matches your required detail density, as heavy curves can introduce local texture stretching if tangent handles are adjusted excessively.
Toggling the Tangent Warp (prop_tangent_warp) checkbox on a region
updates the
canvas display:
The Material Properties panel is the primary dashboard for adjusting the texture generator. All calculations are executed in a non-destructive 16-bit processing pipeline, preserving color depth and avoiding compression artifacts. Adjusting any slider dynamically updates the 2D Preview and 3D Viewport in real time.
The Albedo map defines the base color of the material, free from directional lighting, reflections, and shadowing.
prop_delight): Removes shadows and directional
lighting from the input image. This uses light vector approximation to digitally relight the
texture.
Normal maps store surface normal vectors in RGB channels to simulate fine detail and lighting interactions. SURFACE generates tangent-space normal maps using a multi-frequency decomposition algorithm.
prop_overall_strength): Globally scales the
depth and slope of the generated normal vectors, controlling the visual intensity of surface
details.Displacement (or Height) maps are grayscale images where pixel intensity represents height (white = highest, black = lowest). This map drives parallax occlusion mapping, vertex displacement in the 3D Preview, or tessellation in game engines.
prop_strength): Scales the contrast of the height map,
defining the maximum displacement range.AO maps simulate ambient soft shadows in crevices, cracks, and contact points, improving depth perception.
Roughness maps define surface micro-structures, controlling specular highlights (black = glossy, white = matte/rough).
prop_base_level): Sets the default surface roughness.
Metallic maps define metallic (dielectric vs. conductor) properties (black = non-metal, white = metal).
This engine generates seamless, tileable textures by blending opposing edges using a pathfinding seam blending algorithm.
SURFACE supports stacking regions as layers to blend textures together (e.g., adding moss onto stone). Layers can be reordered or deleted using the layer controls.
The Filters Stack allows stacking post-process filters dynamically. You can toggle filters on/off and configure which PBR channels (Albedo, Normal, Roughness, Metallic, Displacement, AO) are affected.
The 3D Preview uses a GPU-accelerated PBR renderer to validate materials in real time. It features a floating toolbar at the bottom of the panel to configure camera, display, mesh, displacement, lighting, and preset settings.
F): Press F while hovering the 3D
Preview to reset the camera to the default position.Cycle modes using the D key, or reset to default PBR with Shift + D. The
available diagnostic modes are:
| Debug Mode | Description |
|---|---|
| Full PBR | Renders the final material with all PBR channels, lighting, and reflections. |
| Albedo | Renders only the raw base color, free from lighting and shadows. |
| Normal | Renders tangent-space normals mapped to RGB color values. |
| Displacement | Renders the grayscale height map. |
| AO | Renders the ambient occlusion shadow mask. |
| Roughness | Renders the grayscale roughness map (white = rough, black = smooth). |
| Metallic | Renders the metallic mask (white = metal, black = dielectric). |
| IBL Diffuse | Renders diffuse environment lighting contributions. |
| IBL Specular | Renders specular reflections from the environment map. |
| Light Intensity | Renders direct lighting contributions, displaying shadow maps. |
.hdr or
.exr files to the assets/environment/ directory.
The Export Dialog (Ctrl+E) manages asset exporting. You can select and configure
settings for individual regions or pack all crops into a single combined texture atlas.
To optimize performance in game engines, SURFACE supports ORM channel packing. Checking this option packs three grayscale maps into a single RGB texture:
Select naming conventions to match game engine import rules:
_albedo, _normal,
_roughness, _metallic, _ao, _height.
_D (Base Color/Diffuse),
_N (Normal), _ORM (Channel Packed).
_Albedo, _Normal,
_MetallicGloss.
Checking Generate Color Palette extracts the dominant colors from the Albedo map and exports them as a formatted color swatch image sheet, useful for establishing project color palettes.
| Action Parameter | Shortcut Command |
|---|---|
| // GLOBAL FILE & EDIT ACTIONS | |
| New Project Workspace | Ctrl + N |
| Load Project File | Ctrl + L |
| Save Project Matrix | Ctrl + S |
| Save Project As | Ctrl + Shift + S |
| Import Image Resource Asset | Ctrl + I |
| Open Export Panel Interface | Ctrl + E |
| Undo Last Action Parameter | Ctrl + Z |
| Redo Action Parameter | Ctrl + Y or Ctrl + Shift + Z |
| Toggle Hub Welcome Home Screen | H |
| // CANVAS TOOLS & SNAPPING (HOVER CANVAS) | |
| Select Rectangle Crop Tool | R |
| Select Custom Region Crop Tool | C |
| Select Marquee Selection Tool | M |
| Select Text Label Tool | T |
| Toggle Grid Point Snapping | S |
| Toggle Selected Region Lock | L |
| Toggle Uniform Aspect Constraint | U |
| Delete Selected Element | Delete |
| Copy Selected Element | Ctrl + C |
| Paste Element from Clipboard | Ctrl + V |
| Duplicate Active Selection | Ctrl + D |
| // 3D PREVIEW VIEWPORT (HOVER VIEWPORT) | |
| Focus Camera on Selection Bounds | F |
| Cycle Debug Render View Mode | D (Shift+D to reset) |
| Cycle Preview Mesh Type (Sphere, Plane, etc.) | M |
| Cycle Environment Skybox / IBL Map | E |
| Toggle Showcase Rotating Animation Mode | S |
| Toggle Real-Time Pipeline Processing Updates | R |
| // SYSTEM LAYOUT CONFIGURATIONS | |
| Invoke Core Technical Manual Help | F1 |
| Switch Layout: Default split view | F2 |
| Switch Layout: Split view with properties | F3 |
| Switch Layout: Left / Right split view | F4 |