GefjunScene 1.0 — user manual
GefjunScene is a Blender extension for 3D artists who deliver product models as GLB files for Amazon "View in 3D / View in Your Room" (or Shopify 3D/AR). Before you send a GLB to the seller, it checks the Blender scene and the exported file against a dated retailer profile. Each problem is traced to the object, material or image that causes it. Where a fix is safe it applies it (undoable), and it writes an HTML + JSON report you can hand to your client.
All screenshots in this manual are real captures of Blender 4.5.14 LTS and Google Chrome 152 on Linux, taken by the test harness. None are mock-ups.
Important. Retailers change their rules. The built-in Amazon profile is compiled from public summaries and quoted rejection messages, which are listed with dates inside the profile and in every report. A READY verdict means "no rule in this profile failed". It is not a guarantee of acceptance: Amazon also reviews realism by hand. GefjunScene is not affiliated with Amazon or Shopify.
1. Requirements
| Item | Supported |
|---|---|
| Blender | 4.5 LTS or newer (the manifest requires 4.5.0). Verified on 4.5.14 LTS and 5.2.2 LTS (Linux x64, GUI and headless). 5.0, 5.1 and releases after 5.2.2 are untested. |
| Operating system | Linux verified. Windows and macOS were not tested; the code is pure Python with no platform-specific parts. |
| Standalone checker | Python 3.8+ (tools/glbcheck.py, no Blender needed) |
| Network | None. GefjunScene never connects to the internet. |
2. Install
- Unzip
GefjunScene-1.0.0.zip. Inside is the extension packagegefjunscene-1.0.0.zip. Install that inner ZIP; do not unzip it. - In Blender: Edit › Preferences › Get Extensions, then the ▾ menu at the top right, then Install from Disk…, and pick
gefjunscene-1.0.0.zip. - In the 3D Viewport press N. A GefjunScene tab appears in the sidebar.
To install from the command line instead:
blender --command extension install-file -r user_default -e gefjunscene-1.0.0.zipTo uninstall, use Preferences › Get Extensions › GefjunScene › Uninstall, or blender --command extension remove user_default.gefjunscene.
3. Quick start with the example stool
Open examples/bar_stool_problem.blend. The bar stool contains the mistakes that typically get a GLB rejected:
- a specular tweak that exports
KHR_materials_specular; - brushed-steel anisotropy that exports
KHR_materials_anisotropy; - a 3000×2000 texture;
- no metallic/roughness maps;
- double-sided materials;
- the whole product floating 5 cm above the floor;
- a camera and a light inside the product collection.
3.1 Set up the check
In the GefjunScene sidebar tab:
- Export set: choose Collection and pick the product collection (
BarStool), or choose Selected objects. - Profile: choose Amazon View in 3D (or Shopify 3D / AR, or Custom JSON).
- Listing dimensions (assembled): type the width, depth and height from the product listing and choose the unit. Width runs along Blender X, depth along Y and height along Z, with the product's front facing −Y (Blender's Front view).
- Tolerance %: the allowed difference per axis (default 3 %).
- Placement: Floor checks that the product stands on Z = 0, centred at the origin. Wall / ceiling skips the floor check.
Click Run Preflight. No files are written by this step.
The Results panel shows the verdict (NOT READY, READY WITH WARNINGS or READY), the counts, and one row per finding. Click a row to see what is wrong, where it is, and what to do.
- Select Objects selects the objects involved. For a material or image finding, it selects the objects that use it.
- The second button applies the matching safe fix, when there is one.
- Tick Show passed checks to list the PASS rows as well.
3.2 Fix
Safe fixes act only on the export set. Each one is a single undo step (Ctrl+Z), and none of them overwrites a source image file.
| Fix | What it changes |
|---|---|
| Reset glTF specular | Sets Specular IOR Level to 0.5 and Specular Tint to white on unlinked inputs, which removes KHR_materials_specular. Linked inputs are only reported. |
| Zero unsupported Principled inputs | Sets inputs whose extension is not on the allowlist to 0 (for Amazon: Anisotropic). |
| Make single-sided | Turns on Backface Culling. Blender's default (off) is exported as doubleSided: true. |
| Place on floor at origin | Moves the root objects so the product's lowest point is at Z = 0 and its footprint is centred on the origin. |
| Add constant PBR maps | For materials whose Base Color / Metallic / Roughness are plain values, writes PNG maps into the Maps folder and connects them: a base-colour PNG, plus a metallic-roughness PNG wired through Separate Color (G = roughness, B = metallic). Its size is the profile's minimum (2048 px for Amazon). |
| Square power-of-two textures | Writes resized copies of failing textures into the Maps folder and switches the material to the copy. It picks the largest power of two not above the source size, within the profile range, so 3000×2000 becomes 2048×2048. The original image stays untouched. |
The Maps folder defaults to //gefjun_maps/ (next to the .blend). Save the .blend first, or set an absolute folder in Safe Fixes (undoable).
Two things stay manual, and GefjunScene tells you about them:
- UVs outside 0–1 (
UV-RANGE). Open the UV Editor, select all and run UV › Pack Islands. - Wrong scale (
DIM-MATCH). GefjunScene names likely unit slips. For example, "Every axis is about 39.37 x the listing: likely modelled in inches but exported as metres (scale by 0.0254)" forexamples/floor_lamp_inches.blend.
3.3 Export and hand over
In Export and Report, set the Output folder (default //gefjun_delivery/) and, optionally, a File name. Then click Export GLB + Report. GefjunScene:
- exports exactly the export set as GLB with locked settings: +Y up, modifiers applied, no cameras, no lights, no animations, PNG/JPEG images, no Draco;
- reads the exported file back (it does not trust the scene alone) and checks extensions, triangles, textures, maps, double-sided materials, alpha, UV range, floor and centre, and the size against the listing;
- writes
<name>.glb,<name>.preflight.htmland<name>.preflight.json.
Your selection and active object are restored afterwards.
Open Last Report opens the HTML report in your browser. The report works offline and contains no scripts. Every result is labelled in text (✖ FAIL, ▲ WARN, ℹ INFO, ✔ PASS) as well as colour, and the report lists the profile sources with their dates.
Check Existing GLB… runs the GLB part of the checks on any .glb file and writes the report next to it.
4. Keyboard use
Everything is reachable without the mouse:
- N toggles the sidebar.
- F3, type
gefjunscene, and the full action list appears: Run Preflight, Next/Previous Finding, Select Finding Objects, Fix Current Finding, each safe fix, Export GLB + Report, Check Existing GLB, Open Last Report, Save Editable Profile Copy. The same actions are under Object › GefjunScene, and Export is also under File › Export. - Next Finding and Previous Finding move through the results, and the status bar shows the selected finding.
- Fix Current Finding applies the safe fix offered for that finding. Ctrl+Z / Ctrl+Shift+Z undo and redo it.
- While editing a number field (for example the listing width), Tab moves to the next field.
5. What is checked
Scene checks run before export; GLB checks run on the exported file. Severity follows the profile: FAIL, WARN, INFO or PASS.
| Code | Meaning |
|---|---|
SET-EMPTY | The export set has no visible geometry |
SET-HIDDEN | Hidden or unselectable objects are in the collection (they will not be exported) |
SET-EXCLUDED | Cameras or lights in the export set (left out automatically) |
SET-ANIM | Animation, armatures or shape keys (exported as a static pose) |
UNIT-SCALE | Scene unit scale is not 1 |
GEO-TRIS / GLB-TRIS | Triangles after modifiers / in the GLB (counted per instance) against the limit |
GEO-NEGSCALE | Mirrored (negative-scale) objects |
GEO-LOOSE | Zero-area faces, loose vertices or loose edges |
UV-MISSING / UV-RANGE / GLB-UV | No UV map on a textured mesh; UVs outside 0–1 |
MAT-MISSING | Mesh without material |
MAT-SHADER | Surface not driven by a Principled BSDF |
MAT-SPECULAR | Will export KHR_materials_specular |
MAT-EXT | A Principled input exports an extension that is not allowed |
MAT-DOUBLE / GLB-DOUBLE | Double-sided materials |
MAT-ALPHA / GLB-ALPHA | Alpha below 1 (alpha mode BLEND) |
MAT-PBR | Summary PASS: every material translates to allowed glTF PBR |
MAT-MAPS / GLB-MAPS | Base Color or Metallic/Roughness not textured when the profile requires maps |
TEX-MISSING | Image file missing or empty |
TEX-SIZE / GLB-TEX | Not square, not a power of two, too large (FAIL) or below the quoted minimum (WARN); also format and data-URI images |
DIM-MATCH / GLB-DIMS | Size against the listing, with unit-slip and axis-swap hints |
PLC-FLOOR / GLB-BOUNDS / GLB-CENTER | On the floor (Z = 0 in Blender, Y = 0 in glTF) and centred |
GLB-HEADER | GLB container and JSON chunk well formed |
GLB-SIZE | File size against the warning and maximum sizes |
GLB-EXT | extensionsUsed / extensionsRequired against the allowlist |
GLB-CAMERAS / GLB-LIGHTS / GLB-ANIM / GLB-SKIN | Cameras, lights, animations, skins or morph targets in the file |
Amazon's guides also ask you to run the Khronos glTF-Validator before submitting. GefjunScene does not replace it: run it as well (it is free). In our package test, Khronos glTF-Validator 2.0.0-dev.3.10 reported 0 errors and 0 warnings for the fixed stool. It also reported 0 errors for the unfixed stool, which still carries KHR_materials_specular, double-sided materials and a 5 cm float. That is why retailer rules need their own check.
6. Profiles
The built-in profiles are:
amazon-view-in-3d, version 2026.10:- ≤ 200,000 triangles (75,000 recommended);
- textures 2048–4096 px, square, power of two, PNG/JPEG, embedded;
- Base Color + metallicRoughness maps on every material;
- allowed extensions: draco, clearcoat, emissive_strength, ior, sheen, transmission, volume, basisu, texture_transform, xmp_json_ld;
- no cameras, lights or animations;
- double-sided materials, alpha blend and UVs outside 0–1 are warnings;
- a 5 MB advisory size (the sources disagree on this);
- floor tolerance 1 mm; dimension tolerance 3 %.
shopify-3d, version 2026.10: ≤ 500 MB, with a warning above 15 MB (the size at which Shopify optimises files automatically). Texture and extension rules are off.
To adapt a profile, for example when your seller receives different numbers, click Save Editable Profile Copy. This writes a JSON copy and selects it as the Custom JSON profile. Edit the copy in any text editor. Ready-made copies are in examples/profiles/. A broken profile is rejected with the line, the column and the offending keys named.
Rule keys (in "rules"):
triangles_max,triangles_recommendedfile_size_warn_mb,file_size_max_mbtexture_mime_types,texture_min_px,texture_max_px,texture_square,texture_potextensions_allowed(null= any)require_base_color_texture,require_metallic_roughness_textureforbid_cameras,forbid_lights,forbid_animationsskins_morphs,double_sided,alpha_blend,uv_outside_unit(each"fail","warn"or"ignore")embedded_images_onlyfloor_tolerance_m,center_tolerance_ratio,dimension_tolerance_pct
7. Batch and command line
Inside Blender, headless. Uses the settings saved in the .blend unless you override them:
blender -b product.blend --python tools/gefjun_headless.py -- \
--collection BarStool --profile amazon-view-in-3d --dims 38x38x78 --unit cm \
--out ./delivery --stem BarStool \
--fix reset_specular,single_sided,floor_origin,constant_maps,pot_textures,clear_ext_inputs- Add
--check-onlyfor scene checks without export. --glb file.glbinspects an existing GLB.- Fixes made by
--fixare not saved back into the .blend. - Exit codes: 0 no FAIL, 2 FAIL findings, 1 usage or runtime error.
Without Blender. Checks any GLB with the same code that ships in the extension:
python3 tools/glbcheck.py BarStool.glb --dims 38x38x78 --unit cm
python3 tools/glbcheck.py BarStool.glb --profile examples/profiles/amazon-view-in-3d.custom.json --json-only8. Troubleshooting
| Message | What to do |
|---|---|
| Choose the product collection in 'Export set' first. | Pick a collection, or switch to Selected objects. |
| Save the .blend first, or choose an absolute output folder. | // paths are relative to the .blend; save it or use an absolute folder. |
| Profile … is not valid JSON (line N, column M) / Profile is not valid: … | Fix the custom profile at the reported place, or switch back to a built-in profile. |
| File is too short to be a GLB / This is a .gltf JSON file, not a binary .glb | Check Existing GLB reads binary .glb files only. |
| … is driven by nodes; bake them manually | Safe fixes do not rewrite node setups. Bake the result to an image texture. |
DIM-MATCH FAIL with a unit hint | Scale the product by the factor named, then apply scale (Ctrl+A › Scale). |
9. Supported and not supported
Supported:
- Blender 4.5 LTS and 5.2 LTS (4.5.14 and 5.2.2 verified).
- Collection or selection export sets, including nested collections.
- Mesh, curve, surface, text and metaball objects, and collection instances.
- Principled BSDF materials.
- PNG and JPEG textures, including packed images.
- GLB 2.0 reading, with node TRS/matrix transforms, instancing, and triangle strips and fans.
Not supported in 1.0:
.gltf+.binor USDZ export.- Draco or Meshopt settings.
- Overlapping-UV detection.
- Baking procedural materials.
- Full Khronos validation.
- Wall or ceiling placement rules beyond skipping the floor check.
- Geometry-nodes instances: the scene triangle count is an estimate, and the GLB count is authoritative.
- Any upload to Amazon or Shopify.
10. Privacy and licence
GefjunScene runs entirely on your computer. It makes no network connections, collects no telemetry and has no account or licence server. It writes only the files you ask for: the GLB, the reports and the generated or resized textures. See PRIVACY.md.
GefjunScene is free software under the GNU GPL v3 or later (see LICENSE), as Blender add-ons must be GPL-compatible.