Canvas Issues

How the card tier system works

Knowing the tiers helps you tell why a card looks different from what you expected.

Each tier shows everything the tier below it does, plus more. Clicking a Tier 1 card opens its Tier 2 renderer. The tier switcher in the card header moves between all three, and a tier you pick there stays pinned for that card. Cards don't mount a 3D viewer until you open Tier 2, because each viewer takes its own WebGL context.

Cards not rendering

If a canvas card shows a blank area or an error state instead of content:

Card shows only its status

• Job still running. The card shows its metrics once the job completes. Check the status badge on the card.
• Job failed. A failed job's card shows the failure. Run ivybloom jobs status JOB_ID for the error detail.
• Normalizer error. After the job completes, a normalizer turns the raw result into the card's fields. If it hits data it doesn't expect, the card has nothing to show. Check the browser console for errors that mention the normalizer.
• Missed completion event. If the event stream dropped when the job finished, the card may have missed the update. Reload the page to fetch the latest state.

Card preview opens but the visualization is empty

• Data shape mismatch. The renderer expects a specific shape (tables, arrays, key-value pairs). If the result doesn't match, the renderer has nothing to draw. This can happen with new or experimental tools.
• Missing visualization library. Some renderers (charts, molecule grids, 3D viewers) load their libraries on demand. If a library fails to load (network error, blocked by an extension), the renderer stays empty. Reload the page and check the console for failed downloads.
• Tool without a dedicated renderer. A tool without its own renderer falls back to a generic field view.

Card shows "Error rendering card"

• JavaScript error in the renderer. Open the browser console (F12) and look for the error. Common causes: a property read on incomplete data, or a type mismatch in the normalizer output.
• WebGL context lost. If a 3D viewer loses its WebGL context (GPU driver crash, too many contexts), the card shows an error. Close other 3D viewers, then reload the page.
• Memory limit. If the tab is low on memory, a complex card may fail to render. Close other tabs and cards to free resources.

3D viewer blank or broken

The 3D molecular viewers (Mol*, NGL, 3Dmol.js) need WebGL and a working GPU.

Blank white or black viewer:

1. Check WebGL support. Navigate to chrome://gpu (Chrome) or about:support (Firefox). If WebGL isn't "Hardware accelerated", your GPU or drivers don't support it.
2. Update GPU drivers. This is the most common fix. Download the latest drivers from your GPU manufacturer (NVIDIA, AMD, Intel).
3. Check hardware acceleration. In Chrome: Settings then System then "Use hardware acceleration when available" must be on.
4. Close other WebGL consumers. Other 3D web pages and GPU-accelerated video compete for WebGL contexts.
5. Check for extension interference. Some privacy extensions block WebGL to stop fingerprinting. See Browser & cache.

Structure loads but looks wrong:

• Missing atoms. If the PDB file has incomplete residues or non-standard atom names, the viewer may skip them. Check the file's REMARK 465/REMARK 470 lines for missing residues and atoms.
• Wrong representation. The default representation (cartoon for proteins, ball-and-stick for ligands) may not suit your structure. Switch styles with the viewer's representation controls.
• Assembly vs asymmetric unit. A deposited entry's asymmetric unit may not be the biological assembly (multimer) you expect. Use the viewer's assembly controls where it offers them.
• Ligand not visible. A ligand in a protein-ligand complex may be hidden behind the protein surface. Rotate the structure or make the surface transparent.

Viewer controls unresponsive:

• Click inside the viewer first to give it focus.
• On a macOS trackpad, drag to rotate, pinch to zoom, and two-finger scroll to translate.
• If the viewer froze, its WebGL context may have been lost. Close the card's visualization and open it again, or reload the page.
• Check whether JavaScript errors in the console are stopping event handlers.

Browser-specific issues:

Export failures

Right-click a card and choose Export to download its data as a JSON file. PDF, DOCX and CSV files come from the platform's report exports instead. Export issues are usually format-specific.

PDF export

• Blank 3D snapshot. A PDF captures a 2D snapshot of a 3D viewer. If the viewer hadn't finished rendering, the snapshot is blank. Wait for the viewer to load fully before exporting.
• Missing charts. Charts render in the browser. A chart with a very large number of points may not finish before the snapshot is taken. Filter the data first.
• Large file size. PDFs with many embedded molecule images can be large. This is normal.

CSV export

• Missing columns. A CSV holds the card's table. For the full result, use Copy data from the card menu or download the job's outputs with ivybloom jobs download JOB_ID.
• Number formatting. Scientific notation values (for example 1.23e-4) are exported as-is. Some spreadsheet applications misread them, so format the column as a number after import.
• Commas in data. Values containing commas are quoted. If your CSV reader doesn't handle quoted fields, use a reader that does.

JSON export

• Large results. For very large result sets, download the job's outputs with ivybloom jobs download JOB_ID instead of exporting from the card.
• Nested structure. The card export wraps the result with the card's title, card id, job id and job type. The result itself is under the data key.

Card tier not upgrading

If a card seems stuck at a lower tier than expected:

• Check the job status. A card shows its metrics only after the underlying job completes.
• Normalizer latency. After a job completes, the normalizer runs to transform results. This is usually quick but takes longer for very large results.
• Missing normalizer. A job type without a dedicated normalizer shows its fields in a generic view.
• Pinned tier. If you picked a tier in the card header's tier switcher, the card stays there. Pick another tier to change it.
• Stale data. Reload the page to refetch the job result and rerun the normalizer. If that doesn't help, hard refresh with Ctrl+Shift+R (Cmd+Shift+R on macOS).

Performance with many cards

The canvas handles many cards, but it slows down as the count grows, most of all with 3D viewers.

Improving canvas performance:

1. Keep cards at Tier 1 unless you're reading them. A Tier 1 card doesn't mount its renderer, which frees CPU and GPU.
2. Remove cards you no longer need. Select them and press Delete or Backspace. Cmd/Ctrl+Z undoes the removal.
3. Limit simultaneous 3D viewers. Each viewer takes its own WebGL context, and browsers cap the number of contexts per page.
4. Close other browser tabs. Each tab with the platform open uses memory independently.

Missing visualizations

If a card shows data but a specific visualization is missing (no chart, no molecule image, no 3D viewer):

• Normalizer did not produce visualization data. The normalizer for this job type may not extract the fields the visualization needs. Use Copy data from the card menu to see whether the data is present but unmapped.
• Unsupported job type. New or experimental tools may not have a visualization mapping yet. The card falls back to a generic view.
• Missing 2D structure. Molecule images need a valid SMILES in the result. If the SMILES is missing or invalid, no 2D structure renders.
• Chart library not loaded. Chart libraries load on demand. If the download failed (network issue, ad blocker), charts don't appear. Check the browser console for failed network requests.
• Insufficient data for visualization. Some charts need a minimum number of points (a dose-response curve needs several concentrations). Below that, the chart is skipped.

Card data stale

If a card shows outdated data even though the job has completed with new results:

• Missed update. If the event stream dropped while the job was completing, the card may not have received the update. Reload the page to sync.
• Multiple browser tabs. If the same project is open in several tabs, a tab that missed the update shows stale data until you reload it.
• Local cache. If a reload doesn't help, clear site data for ivybiosciences.com and sign in again.

Canvas keyboard shortcuts

These shortcuts work when focus isn't in a text field. Click the canvas background first if they don't respond.

Canvas layout and organization

If your canvas feels disorganized or hard to navigate:

• Drag to reorder. Drag cards to rearrange them on the canvas.
• Remove finished work. Select cards you no longer need and delete them. Their jobs and outputs stay in your project.
• Ask about a card. Right-click a card and choose Ask about this or Explain results to pull it into your next chat message.

Ticket checklist

If you need to contact support about a canvas issue:

• Project ID and the job IDs of the affected cards
• Screenshot of the canvas showing the issue
• Browser name and version
• GPU model (check chrome://gpu or equivalent)
• Number of cards currently on the canvas
• Whether the issue occurs in incognito mode
• Browser console errors (F12 then Console tab)