Troubleshooting & FAQ
Common questions and issues when using GemDiagram.
Design & Editor
Q: The stone won't render in the viewport.
A: Check the browser console (F12 → Console) for error messages. Common causes:
- Too many facets: Realistic mode has a 256-plane cap. If your design exceeds it, switch to Solid mode. The console logs "Realistic render: X planes exceeds cap 256; using Solid."
- Bad geometry: A tier might have an invalid angle or distance. Try removing the problematic tier and re-adding it.
- Browser compatibility: GemDiagram requires WebGL support. Try a recent Chrome, Firefox, Safari, or Edge.
Q: The design looks different in Realistic vs. Solid mode.
A: That's expected. Solid mode is instant flat shading; Realistic mode ray-traces light. The Realistic view is more accurate to how the stone actually looks. Switch to Realistic before exporting screenshots or videos for promotion.
Q: The tier angles don't match what I typed.
A: If Auto-distance is enabled, changing angle recalculates distance to keep the facet anchored to the girdle. Turn off Auto-distance if you want independent control over both values.
Materials & Optics
Q: What's the difference between all the materials?
A: Mainly refractive index (RI) and dispersion. Higher RI = more sparkle; higher dispersion = more "fire" (colored flashes).
- Diamond: RI 2.417, dispersion 0.044 — the brightest and most fiery.
- Moissanite: RI 2.650, dispersion 0.104 — brighter and more fiery than Diamond.
- Ruby: RI 1.768, dispersion 0.018 — less sparkle, but beautiful red body color.
See Choosing a Material for the full 22-material table.
Q: Why does the Alexandrite look gray?
A: Alexandrite's pleochroism (the color-by-direction property) requires Realistic render mode and appropriate lighting direction. In Solid mode, it shows as gray because flat shading doesn't model directional colors. Switch to Realistic mode and rotate the stone to see the three colors.
Q: The critical angle warning appears even though I think my pavilion is OK.
A: The warning triggers when the pavilion-mains angle falls below the material's critical angle. For Ruby (critical 23.1°), a pavilion at 22° causes windowing. Check the exact angle in the Build panel and compare it to the critical angle shown in the Material card. See Refractive Index & Dispersion for an explanation.
Importing & Exporting
Q: I imported a .gem file, but it doesn't show the material name.
A: GemCad files don't always include material names. GemDiagram snaps to the closest material by refractive index. Check the Material dropdown — it might be close but not exact. You can change it manually if needed.
Q: Can I open GemCAD or Gem Cut Studio files in GemDiagram?
A: Yes. Import a .gem/.asc file (GemCAD) or a .gcs file (Gem Cut Studio) from the top bar and it renders in 3D immediately — see GemDiagram vs GemCAD and GemDiagram vs Gem Cut Studio for what imports and what doesn't. Imports open read-only; click Save to keep an editable .facet copy.
Q: The PDF report looks wrong or is cut off.
A: Try opening it in a different PDF viewer (not your browser's built-in). Some viewers have scaling or rendering issues. Adobe Acrobat or Preview (Mac) usually work well.
Q: Can I edit the PDF after exporting?
A: No. PDF is a snapshot (read-only). Always keep the .facet file as your source; export PDF as outputs. If you want to change the design, edit the .facet in GemDiagram and re-export.
Video & Screenshots
Q: The video is too large / takes too long to export.
A: Video export uses Realistic mode, which requires GPU rendering and can be slow (30 seconds of 1080p takes 1–5 minutes depending on your machine). Switch to Solid mode if you want a faster screenshot. Videos are ~50–100 MB; if that's too large, use a video compressor tool offline.
Q: The screenshot is blurry or too small.
A: Export at the viewport's current resolution. If you need larger/sharper, resize your browser window larger, then screenshot again. Or use an image upscaler tool offline (AI-powered tools work well for screenshots).
Browser & Performance
Q: Will GemDiagram run on my computer?
A: Check System Requirements — it covers the OS, browser, GPU, and RAM you'll need. If the app won't start, see the troubleshooting steps there (usually WebGL2 needs to be enabled in your browser settings).
Q: GemDiagram is slow / laggy when I edit.
A: Causes:
- Realistic mode with many facets: Switch to Solid mode while editing. Realistic mode is slow intentionally (it's ray-traced). Use Realistic only for final preview and export.
- Old GPU or browser: GemDiagram needs WebGL 2.0 (GPU rendering). On old machines, performance suffers. Upgrade your browser or graphics driver if possible.
- Auto-rotate enabled: Disable Spin (toggle S or the button) to reduce GPU load.
Q: The webapp disconnects or goes blank.
A: GemDiagram runs in your browser — no server connection is needed for the Developer editor (except for account features on Pro plans). If the page goes blank:
- Reload the page (F5 or Cmd+R).
- Check your internet connection (it shouldn't matter, but refresh anyway).
- Open the browser console (F12 → Console) and check for errors. Report errors to support if they persist.
Accounts & Plans
Q: Do I lose my designs if I downgrade?
A: No. Your designs stay in your account. You can still open and edit them at the lower tier's feature level. If you downgrade from Studio to Starter, you can't access Rough Planner or Ray Studio, but your designs are safe.
Q: Can I use GemDiagram offline?
A: The Developer editor works offline (no internet needed after the page loads). However, the main site and account features require internet. Save your .facet files frequently so you have local backups.
Getting Help
- Browser console errors: Press F12, go to Console, and copy any error messages. Include them when reporting issues.
- Design doesn't look right: Take a screenshot and describe what's wrong.
- Feedback or feature requests: Use the feedback form on the website.
For more help, see the full documentation index.