Troubleshooting Common Issues with Millensys DICOM MiniViewerThe Millensys DICOM MiniViewer is a lightweight, web-based viewer designed for rapid access to DICOM studies. While it’s built for simplicity and reliability, users can still encounter problems related to network connectivity, image rendering, compatibility, and user settings. This article walks through common issues, diagnostic steps, and practical fixes so radiologists, technologists, IT staff, and clinical users can restore full functionality quickly.
1. Viewer won’t load or page is blank
Symptoms:
- Web page loads but the viewer area remains blank or shows a spinning loader.
- Browser displays errors such as “Failed to load resource” or “Connection refused.”
Causes and checks:
- Network connectivity or firewall blocking access to the MiniViewer server or PACS.
- Server offline: the MiniViewer backend or the DICOM web service (WADO/REST) is down.
- Incorrect URL or proxy misconfiguration.
- Browser blocking mixed content (HTTPS page trying to load HTTP resources) or blocking third‑party scripts.
Troubleshooting steps:
- Confirm server status: ping the MiniViewer host and check service/process status on the server.
- Open browser dev tools (Console/Network) to view failed requests and HTTP status codes.
- Ensure the URL and ports are correct; if using a proxy, verify proxy settings for the browser.
- If mixed-content warnings appear, serve all resources via HTTPS or adjust server configuration.
- Temporarily disable browser extensions (ad blockers, script blockers) and test again.
- Check firewall rules for the network segment and ensure WADO/REST endpoints are reachable from the client.
When to escalate:
- Server logs show repeated internal errors or crashes.
- Network diagnostics indicate intermittent packet loss that IT cannot resolve quickly.
2. Studies load slowly or images lag when scrolling
Symptoms:
- Delay when opening series or changing images.
- Pixelated images initially that improve after a moment.
- Slow thumbnails generation.
Causes and checks:
- Large studies or high-resolution images being transferred over limited bandwidth.
- Server-side performance bottlenecks (CPU, memory, or I/O).
- Client device resource limits (low RAM, slow CPU).
- Inefficient caching or lack of prefetching configuration.
Troubleshooting steps:
- Measure bandwidth and latency between client and server (use ping/traceroute and bandwidth tests).
- Review server resource usage during heavy use (CPU, RAM, disk I/O).
- Check MiniViewer configuration for caching and prefetch settings—enable or tune prefetching if available.
- Reduce image transfer by using downsampled previews or forcing lossy compression for web delivery if clinically acceptable.
- Test on another machine/network to determine if issue is client- or network-specific.
- Clear browser cache or try a different browser to rule out client-side caching issues.
When to escalate:
- Evidence of server resource saturation or disk I/O waits.
- Network saturation across multiple users indicating infrastructure-level limits.
3. Incorrect or missing patient/study information
Symptoms:
- Patient name, ID, or study date shows as blank or mismatched.
- Studies appear under wrong patient records.
Causes and checks:
- DICOM tag inconsistencies or anonymization scripts that removed identifying tags.
- Matching/mapping issues between PACS and MiniViewer (wrong AE Titles, query/retrieve filters).
- Character encoding problems (non-ASCII characters becoming garbled).
Troubleshooting steps:
- Verify DICOM tags in the study using a DICOM tag viewer (check PatientName, PatientID, StudyInstanceUID).
- Confirm PACS sends complete metadata and that any anonymization scripts are not applied unintentionally.
- Check MiniViewer mapping rules and query parameters used to fetch study lists from the PACS.
- If character encoding issue suspected, ensure server and viewer use UTF-8 and that DICOM Specific Character Set is honored.
- Re-index the study on the PACS if indexing errors are suspected.
When to escalate:
- PACS-side tag corruption or patient data integrity problems that require PACS vendor intervention.
4. Images appear distorted, wrong orientation, or black/white inversion
Symptoms:
- Images rotated, flipped, or mirrored.
- Window/level settings produce inverted contrast (bones dark, not bright).
- JPEG artifacts or corrupted frames.
Causes and checks:
- DICOM attributes for orientation (Image Orientation (Patient), Image Position) misinterpreted.
- Incorrect application of photometric interpretation (MONOCHROME1 vs MONOCHROME2).
- Corrupted transfer syntax handling, or unsupported compression codec on client.
- GPU/browser rendering differences.
Troubleshooting steps:
- Inspect DICOM tags: Photometric Interpretation, Samples per Pixel, Bits Allocated, Image Orientation (Patient).
- If Photometric Interpretation is MONOCHROME1, ensure viewer supports automatic inversion or enable inversion in settings.
- Confirm the transfer syntax used (e.g., JPEG2000, RLE). Ensure the MiniViewer or server-side transcoder supports the codec. If not, enable server-side transcoding to a supported syntax.
- Test in another browser or disable GPU acceleration to check for rendering differences.
- Re-transfer the study from modality to PACS to rule out corruption during storage.
When to escalate:
- Corrupted frames stored in PACS; require origin device or PACS vendor to re-send or repair.
5. Hanging, freezing, or browser crashes when viewing large series
Symptoms:
- Browser tab becomes unresponsive while scrolling through large series.
- High CPU or memory usage reported by the browser.
Causes and checks:
- Client machine running out of memory due to too many images loaded into memory.
- Memory leaks in the viewer or inefficient image caching strategy.
- Large uncompressed images consuming resources.
Troubleshooting steps:
- Monitor browser task manager to check memory/CPU consumption.
- Close other tabs/applications to free resources; test with a machine that has more RAM.
- Configure the viewer to limit number of cached slices or enable viewport-based loading (load only around current slice).
- Enable server-side or streaming decimation (lower resolution tiles) for initial rendering.
- Update browser to latest stable version and ensure OS graphics drivers are current.
When to escalate:
- Reproducible memory leaks: provide logs/heap profiles to the vendor for a fix.
6. Measurements, annotations, or tools not saving
Symptoms:
- Drawn measurements or annotations disappear after refresh or are not persistent across sessions.
- Snapshots/exported images missing overlays.
Causes and checks:
- Annotations stored locally (client-side) rather than persisted to server/PACS.
- Insufficient user permissions to write annotations to the server or PACS.
- Misconfigured annotation storage endpoint (DICOM SR, XDS, or proprietary store).
Troubleshooting steps:
- Verify where the MiniViewer is configured to store annotations (localStorage vs server vs PACS).
- Check user account permissions for annotation write access.
- Inspect network calls when saving annotations to ensure correct endpoints respond with success (HTTP 200).
- Confirm whether annotations are being exported as DICOM SR or burned into images and adjust workflow to match site policy.
- If annotations rely on a separate annotation server, ensure that server’s API is reachable and authenticated.
When to escalate:
- Permissions or PACS configuration requiring admin changes.
7. Authentication, SSO, or permission errors
Symptoms:
- Users cannot log in, SSO fails, or permission-denied errors when accessing studies or tools.
Causes and checks:
- SSO (SAML/OAuth) configuration mismatch between identity provider (IdP) and MiniViewer.
- Expired certificates used for SAML assertions or HTTPS endpoints.
- Role-based access control (RBAC) misconfigured.
Troubleshooting steps:
- Check SSO logs on both IdP and MiniViewer sides to see assertion errors or signature validation failures.
- Verify certificates and their expiration dates; ensure system clocks are synchronized (NTP).
- Test with a local account to isolate SSO vs application issue.
- Review RBAC mappings for user groups and permissions.
- Ensure MiniViewer is configured to accept attributes (e.g., username, email, roles) as provided by IdP.
When to escalate:
- SAML assertion signature or certificate problems that need IdP or vendor support.
8. Printing or exporting images fails
Symptoms:
- Print dialog fails or exported DICOM/Capture images are incomplete.
- Exported images have wrong window/level or missing overlays.
Causes and checks:
- Print server or DICOM print SCP not reachable.
- Export feature requires additional server-side components or permissions.
- Incorrect export format settings.
Troubleshooting steps:
- Verify network connectivity to the print/DICOM SCP server and correct AE Title/port configuration.
- Check export logs for errors and ensure destination storage has write permission and sufficient space.
- Test different export formats (PNG, JPEG, DICOM Secondary Capture) to isolate issue.
- Confirm whether overlays are burned-in at export time or stored as separate annotation objects and adjust settings accordingly.
When to escalate:
- Print service misconfiguration on enterprise print servers or PACS-side restrictions.
9. Browser compatibility or feature differences
Symptoms:
- Certain features work in one browser but not another (e.g., touch gestures, drag-and-drop).
- Mobile browsers behave differently than desktop ones.
Causes and checks:
- Differences in browser support for WebGL, WebAssembly, or specific JavaScript APIs.
- Touch and pointer event handling vary across platforms.
- Older browser versions missing modern APIs.
Troubleshooting steps:
- Check MiniViewer documentation for supported browsers and minimum versions.
- Test problem scenarios across Chrome, Edge, Firefox, Safari to determine scope.
- Ensure hardware acceleration is enabled if WebGL is required.
- For mobile, use the vendor’s recommended mobile workflow or app if available.
When to escalate:
- Feature regressions that appear after an update—provide browser/OS/version details to vendor.
10. Unexpected errors or crash reports in logs
Symptoms:
- Server or client logs show stack traces, HTTP 500 errors, or unhandled exceptions.
Causes and checks:
- Software bugs introduced by updates.
- Corrupted configuration files or missing dependencies.
- Third-party library incompatibilities.
Troubleshooting steps:
- Collect relevant logs: browser console, MiniViewer server logs, and PACS logs for the time window of the error.
- Reproduce the error in a test environment if possible and capture network traces.
- Check changelogs for recent updates that align with the start of issues.
- Roll back recent changes in a controlled manner if a recent update is suspected.
- Open a ticket with vendor support including logs, steps to reproduce, environment details (browser, OS, MiniViewer version, PACS type).
When to escalate:
- Reproducible crashes or errors with a clear regression path.
Practical checklist for site IT and clinical teams
- Confirm server uptime and health: CPU, RAM, disk I/O, and network.
- Verify ports and firewall rules for WADO/REST, query/retrieve, and ancillary services.
- Confirm supported browsers and versions; enforce standard browser configurations.
- Keep software up to date but stage updates in a test environment first.
- Ensure NTP is configured and certificates are valid.
- Document PACS mapping, AE Titles, and annotation storage locations.
- Establish a support escalation path: collect logs, reproduce steps, and include timestamps.
Final notes
When problems persist after following the steps above, gather precise diagnostic data before contacting Millensys or your PACS vendor: browser console output, server logs, sample DICOMs (with PHI removed if needed), exact steps to reproduce, timestamps, and environment details. That information shortens troubleshooting cycles and helps get fixes deployed faster.
Leave a Reply