Orthanc WSI with webviewer

Hello all, I may be out of place here since I am not a programmer, but a pathologist interested in using this software for viewing whole slide images. I would appreciate any assistance in setting up Orthanc for this purpose. I believe my issue is not being able to appropriately configure the json file to add the plug-in for the webviewer, feel free to see the code below. I am assuming the WSI are viewed through the webviewer just the same as the other DICOM files.
I am using Windows with the dll files as plug-ins. I appreciate any help with getting me off the ground, I essentially just want to import/upload the WSI files to the Orthanc server and view them through the webviewer, nothing fancy.

-Matthew

json configuration file here:

{
  /**
   * General configuration of Orthanc
   **/

  // The logical name of this instance of Orthanc. This one is
  // displayed in Orthanc Explorer and at the URI "/system".
  "Name" : "MyOrthanc",

  // Path to the directory that holds the heavyweight files
  // (i.e. the raw DICOM instances)
  "StorageDirectory" : "OrthancStorage-v6",

  // Path to the directory that holds the SQLite index (if unset,
  // the value of StorageDirectory is used). This index could be
  // stored on a RAM-drive or a SSD device for performance reasons.
  "IndexDirectory" : "OrthancStorage-v6",

  // Enable the transparent compression of the DICOM instances
  "StorageCompression" : false,

  // Maximum size of the storage in MB (a value of "0" indicates no
  // limit on the storage size)
  "MaximumStorageSize" : 0,

  // Maximum number of patients that can be stored at a given time
  // in the storage (a value of "0" indicates no limit on the number
  // of patients)
  "MaximumPatientCount" : 0,
  
  // List of paths to the custom Lua scripts that are to be loaded
  // into this instance of Orthanc
  "LuaScripts" : [
  ],

  // List of paths to the plugins that are to be loaded into this
  // instance of Orthanc (e.g. "./libPluginTest.so" for Linux, or
  // "./PluginTest.dll" for Windows). These paths can refer to
  // folders, in which case they will be scanned non-recursively to
  // find shared libraries.
  "Plugins" : ["C:\Orthanc\OrthancDicomWeb-0.3.dll", "C:\Orthanc\OrthancWebViewer-2.2.dll", "C:\Orthanc\OrthancWSI-0.2.dll"
  ],

  "WebViewer" : {
    "CachePath" : "WebViewerCache",
    "CacheSize" : 10,
    "Threads" : 4
  },

  /**
   * Configuration of the HTTP server
   **/

  // Enable the HTTP server. If this parameter is set to "false",
  // Orthanc acts as a pure DICOM server. The REST API and Orthanc
  // Explorer will not be available.
  "HttpServerEnabled" : true,

  // HTTP port for the REST services and for the GUI
  "HttpPort" : 8042,

  // When the following option is "true", if an error is encountered
  // while calling the REST API, a JSON message describing the error
  // is put in the HTTP answer. This feature can be disabled if the
  // HTTP client does not properly handles such answers.
  "HttpDescribeErrors" : true,

  // Enable HTTP compression to improve network bandwidth utilization,
  // at the expense of more computations on the server. Orthanc
  // supports the "gzip" and "deflate" HTTP encodings.
  "HttpCompressionEnabled" : true,

  /**
   * Configuration of the DICOM server
   **/

  // Enable the DICOM server. If this parameter is set to "false",
  // Orthanc acts as a pure REST server. It will not be possible to
  // receive files or to do query/retrieve through the DICOM protocol.
  "DicomServerEnabled" : true,

  // The DICOM Application Entity Title
  "DicomAet" : "ORTHANC",

  // Check whether the called AET corresponds during a DICOM request
  "DicomCheckCalledAet" : false,

  // The DICOM port
  "DicomPort" : 4242,

  // The default encoding that is assumed for DICOM files without
  // "SpecificCharacterSet" DICOM tag, and that is used when answering
  // C-Find requests (including worklists). The allowed values are
  // "Ascii", "Utf8", "Latin1", "Latin2", "Latin3", "Latin4",
  // "Latin5", "Cyrillic", "Windows1251", "Arabic", "Greek", "Hebrew",
  // "Thai", "Japanese", and "Chinese".
  "DefaultEncoding" : "Latin1",

  // The transfer syntaxes that are accepted by Orthanc C-Store SCP
  "DeflatedTransferSyntaxAccepted" : true,
  "JpegTransferSyntaxAccepted" : true,
  "Jpeg2000TransferSyntaxAccepted" : true,
  "JpegLosslessTransferSyntaxAccepted" : true,
  "JpipTransferSyntaxAccepted" : true,
  "Mpeg2TransferSyntaxAccepted" : true,
  "RleTransferSyntaxAccepted" : true,

  // Whether Orthanc accepts to act as C-Store SCP for unknown storage
  // SOP classes (aka. "promiscuous mode")
  "UnknownSopClassAccepted" : false,

  // Set the timeout (in seconds) after which the DICOM associations
  // are closed by the Orthanc SCP (server) if no further DIMSE
  // command is received from the SCU (client).
  "DicomScpTimeout" : 30,

  /**
   * Security-related options for the HTTP server
   **/

  // Whether remote hosts can connect to the HTTP server
  "RemoteAccessAllowed" : false,

  // Whether or not SSL is enabled
  "SslEnabled" : false,

  // Path to the SSL certificate in the PEM format (meaningful only if
  // SSL is enabled)
  "SslCertificate" : "certificate.pem",

  // Whether or not the password protection is enabled
  "AuthenticationEnabled" : false,

  // The list of the registered users. Because Orthanc uses HTTP
  // Basic Authentication, the passwords are stored as plain text.
  "RegisteredUsers" : {
    // "alice" : "alicePassword"
  },

  /**
   * Network topology
   **/

  // The list of the known DICOM modalities
  "DicomModalities" : {
    /**
     * Uncommenting the following line would enable Orthanc to
     * connect to an instance of the "storescp" open-source DICOM
     * store (shipped in the DCMTK distribution) started by the
     * command line "storescp 2000".
     **/
    // "sample" : [ "STORESCP", "127.0.0.1", 2000 ]

    /**
     * A fourth parameter is available to enable patches for a
     * specific PACS manufacturer. The allowed values are currently
     * "Generic" (default value), "StoreScp" (storescp tool from
     * DCMTK), "ClearCanvas", "MedInria", "Dcm4Chee", "SyngoVia",
     * "AgfaImpax" (Agfa IMPAX), "EFilm2" (eFilm version 2), and
     * "Vitrea". This parameter is case-sensitive.
     **/
    // "clearcanvas" : [ "CLEARCANVAS", "192.168.1.1", 104, "ClearCanvas" ]
  },

  // The timeout (in seconds) after which the DICOM associations are
  // considered as closed by the Orthanc SCU (client) if the remote
  // DICOM SCP (server) does not answer.
  "DicomScuTimeout" : 10,

  // The list of the known Orthanc peers
  "OrthancPeers" : {
    /**
     * Each line gives the base URL of an Orthanc peer, possibly
     * followed by the username/password pair (if the password
     * protection is enabled on the peer).
     **/
    // "peer" : [ "http://127.0.0.1:8043/", "alice", "alicePassword" ]
    // "peer2" : [ "http://127.0.0.1:8044/" ]

    /**
     * This is another, more advanced format to define Orthanc
     * peers. It notably allows to specify a HTTPS client certificate
     * in the PEM format (as in the "--cert" option of curl), or to
     * enable PKCS#11 authentication for smart cards.
     **/
    // "peer" : {
    // "Url" : "http://127.0.0.1:8043/",
    // "Username" : "alice",
    // "Password" : "alicePassword",
    // "CertificateFile" : "client.crt",
    // "CertificateKeyFile" : "client.key",
    // "CertificateKeyPassword" : "certpass",
    // "Pkcs11" : false
    // }
  },

  // Parameters of the HTTP proxy to be used by Orthanc. If set to the
  // empty string, no HTTP proxy is used. For instance:
  // "HttpProxy" : "192.168.0.1:3128"
  // "HttpProxy" : "proxyUser:proxyPassword@192.168.0.1:3128"
  "HttpProxy" : "",

  // Set the timeout for HTTP requests issued by Orthanc (in seconds).
  "HttpTimeout" : 10,

  // Enable the verification of the peers during HTTPS requests. This
  // option must be set to "false" if using self-signed certificates.
  // Pay attention that setting this option to "false" results in
  // security risks!
  // Reference: http://curl.haxx.se/docs/sslcerts.html
  "HttpsVerifyPeers" : true,

  // Path to the CA (certification authority) certificates to validate
  // peers in HTTPS requests. From curl documentation ("--cacert"
  // option): "Tells curl to use the specified certificate file to
  // verify the peers. The file may contain multiple CA
  // certificates. The certificate(s) must be in PEM format."
  "HttpsCACertificates" : "",

  /**
   * Advanced options
   **/

  // Dictionary of symbolic names for the user-defined metadata. Each
  // entry must map an unique string to an unique number between 1024
  // and 65535. Reserved values:
  // - The Orthanc whole-slide imaging plugin uses metadata 4200
  "UserMetadata" : {
    // "Sample" : 1024
  },

  // Dictionary of symbolic names for the user-defined types of
  // attached files. Each entry must map an unique string to an unique
  // number between 1024 and 65535. Optionally, a second argument can
  // provided to specify a MIME content type for the attachment.
  "UserContentType" : {
    // "sample" : 1024
    // "sample2" : [ 1025, "application/pdf" ]
  },

  // Number of seconds without receiving any instance before a
  // patient, a study or a series is considered as stable.
  "StableAge" : 60,

  // By default, Orthanc compares AET (Application Entity Titles) in a
  // case-insensitive way. Setting this option to "true" will enable
  // case-sensitive matching.
  "StrictAetComparison" : false,

  // When the following option is "true", the MD5 of the DICOM files
  // will be computed and stored in the Orthanc database. This
  // information can be used to detect disk corruption, at the price
  // of a small performance overhead.
  "StoreMD5ForAttachments" : true,

  // The maximum number of results for a single C-FIND request at the
  // Patient, Study or Series level. Setting this option to "0" means
  // no limit.
  "LimitFindResults" : 0,

  // The maximum number of results for a single C-FIND request at the
  // Instance level. Setting this option to "0" means no limit.
  "LimitFindInstances" : 0,

  // The maximum number of active jobs in the Orthanc scheduler. When
  // this limit is reached, the addition of new jobs is blocked until
  // some job finishes.
  "LimitJobs" : 10,

  // If this option is set to "false", Orthanc will not log the
  // resources that are exported to other DICOM modalities of Orthanc
  // peers in the URI "/exports". This is useful to prevent the index
  // to grow indefinitely in auto-routing tasks.
  "LogExportedResources" : true,

  // Enable or disable HTTP Keep-Alive (deprecated). Set this option
  // to "true" only in the case of high HTTP loads.
  "KeepAlive" : false,

  // If this option is set to "false", Orthanc will run in index-only
  // mode. The DICOM files will not be stored on the drive. Note that
  // this option might prevent the upgrade to newer versions of Orthanc.
  "StoreDicom" : true,

  // DICOM associations are kept open as long as new DICOM commands
  // are issued. This option sets the number of seconds of inactivity
  // to wait before automatically closing a DICOM association. If set
  // to 0, the connection is closed immediately.
  "DicomAssociationCloseDelay" : 5,

  // Maximum number of query/retrieve DICOM requests that are
  // maintained by Orthanc. The least recently used requests get
  // deleted as new requests are issued.
  "QueryRetrieveSize" : 10,

  // When handling a C-Find SCP request, setting this flag to "true"
  // will enable case-sensitive match for PN value representation
  // (such as PatientName). By default, the search is
  // case-insensitive, which does not follow the DICOM standard.
  "CaseSensitivePN" : false,

  // Configure PKCS#11 to use hardware security modules (HSM) and
  // smart cards when carrying on HTTPS client authentication.
  /**
     "Pkcs11" : {
       "Module" : "/usr/local/lib/libbeidpkcs11.so",
       "Module" : "C:/Windows/System32/beidpkcs11.dll",
       "Pin" : "1234",
       "Verbose" : true
     }
   **/
  
  // If set to "true", Orthanc will still handle "SOP Classes in
  // Study" (0008,0062) in C-FIND requests, even if the "SOP Class
  // UID" metadata is not available in the database (which is the case
  // if the DB was previously used by Orthanc <= 1.1.0). This option
  // is turned off by default, as it requires intensive accesses to
  // the hard drive.
  "AllowFindSopClassesInStudy" : false,

  // If set to "false", Orthanc will not load its default dictionary
  // of private tags. This might be necessary if you cannot import a
  // DICOM file encoded using the Implicit VR Endian transfer syntax,
  // and containing private tags: Such an import error might stem from
  // a bad dictionary. You can still list your private tags of
  // interest in the "Dictionary" configuration option below.
  "LoadPrivateDictionary" : true,

  // Register a new tag in the dictionary of DICOM tags that are known
  // to Orthanc. Each line must contain the tag (formatted as 2
  // hexadecimal numbers), the value representation (2 upcase
  // characters), a nickname for the tag, possibly the minimum
  // multiplicity (> 0 with defaults to 1), possibly the maximum
  // multiplicity (0 means arbitrary multiplicity, defaults to 1), and
  // possibly the Private Creator (for private tags).
  "Dictionary" : {
    // "0014,1020" : [ "DA", "ValidationExpiryDate", 1, 1 ]
    // "00e1,10c2" : [ "UI", "PET-CT Multi Modality Name", 1, 1, "ELSCINT1" ]
    // "7053,1003" : [ "ST", "Original Image Filename", 1, 1, "Philips PET Private Group" ]
    // "2001,5f" : [ "SQ", "StackSequence", 1, 1, "Philips Imaging DD 001" ]
  }

{
  "DicomWeb" : {
    "Enable" : true, // Whether DICOMweb support is enabled
    "Root" : "/dicom-web/", // Root URI of the DICOMweb API (for QIDO-RS, STOW-RS and WADO-RS)
    "EnableWado" : true, // Whether WADO-URI (aka. WADO) support is enabled
    "WadoRoot" : "/wado", // Root URI of the WADO-URI (aka. WADO) API
    "Host" : "localhost", // Hard-codes the name of the host for subsequent WADO-RS requests
    "Ssl" : false // Whether HTTPS should be used for subsequent WADO-RS requests
  }
}

Hello Matthew,

I think your plugin paths have to be escaped.

“Plugins” : [“C:\Orthanc\OrthancDicomWeb-0.3.dll”, “C:\Orthanc\OrthancWebViewer-2.2.dll”, “C:\Orthanc\OrthancWSI-0.2.dll”

Best Regards,
Thibault

Hello,

Indeed, you must either escape backslashes, or replace them with forward slashes. I have just added a clarification in the default configuration file:https://bitbucket.org/sjodogne/orthanc/commits/0f09c1d18584f540c7c58ef02ee6884a73170ba7

Also, have a look at the logs of Orthanc: They show which plugins are loaded.

HTH,
Sébastien-

Thank you! That worked and I am able to see the webviewer buttons. Now I have my next problem, the files that I have converted to DICOM using the FFEI openslide to DICOM converter: https://lists.andrew.cmu.edu/pipermail/openslide-users/2014-August/000895.html give me an error (Error - Cannot get the pyramid structure of the series:...)
It should theoretically convert the files the same was as the DICOMizer you provide, but maybe not. I am trying to learn how to use your DICOMizer to convert the svs whole slide image files to DCM/DICOM files, but have not had much success. If you could please provide more guidance on how to use the DICOMizer to convert svs (or other file formats) to a DICOM format that Orthanc can import succesfully, that would be very helpful. Or if I can send you some of the (DCM) files that the FFEI converter exports, maybe you can see why Orthanc cannot identify the pyramid structure. Please let me know what would be best. Thank you!

-Matthew

Hello,

The full documentation for Orthanc WSI has just been published:
http://book.orthanc-server.com/plugins/wsi.html

It should hopefully answer your questions. If this is not the case, please let us know.

Regards,
Sébastien-

Hello,

Thank you so much for having the documentation available, unfortunately I tried to use it to re-encode the proprietary file formats and am still unsuccessful. I am using 64-bit Windows 10 operating system (do not have experience with Linux) and trying to run the Dicomizer in the Windows Command Prompt Window:
Usage: OrthancWSIDicomizer-0.2.exe [OPTION]... [INPUT]

and have tried this:

C:\Orthanc>OrthancWSIDicomizer-0.2.exe [\Users\Imaging\Downloads\openslide\bin\libopenslide-0.1.dll] [\Users\Imaging\Downloads\1057056.svs]

then I receive the below error:
W1216 12:22:11.042732 FromDcmtkBridge.cpp:189] Loading the embedded dictionaries
W1216 12:22:11.058357 Dicomizer.cpp:804] The input image is: [\Users\Imaging\Downloads\openslide\bin\libopenslide-0.1.dll][\Users\Imaging\Downloads\1057056.svs]
E1216 12:22:11.089608 SystemToolbox.cpp:199] The path does not point to a regular file: [\Users\Imaging\Downloads\1057056.svs][\Users\Imaging\Downloads\openslide\bin\libopenslide-0.1.dll]
E1216 12:22:11.089608 Dicomizer.cpp:895] Terminating on exception: The specified path does not point to a regular file

or this when there is a space between the brackets:
C:\Orthanc>OrthancWSIDicomizer-0.2.exe [\Users\Imaging\Downloads\openslide\bin\libopenslide-0.1.dll] [\Users\Imaging\Downloads\1057056.svs]
W1216 12:26:09.289828 FromDcmtkBridge.cpp:189] Loading the embedded dictionaries
E1216 12:26:09.305453 Dicomizer.cpp:551] Error while parsing the command-line arguments: too many positional options have been specified on the command line

DO you have instructions for using the Dicomizer in the Windows CMD, or am I not entering the commands correctly? I have tried mixing and matching the openslide library and files, however I have not been successful in converting the SVS file to a DICOM file format.

There is also another open-source WSI DICOM converter software (FFEI Sierra):https://lists.andrew.cmu.edu/pipermail/openslide-users/2014-August/000895.html that uses Openslide and Supplement 145 to convert the proprietary file formats to Dicom, and when I try importing those file to Orthanc I receive the following error:
Error- Cannot get the pyramid structure of series...

Any further assistance would be much appreciated. Considering your WSI demo files work very well, that is the goal of what I am trying to accomplish from an end user stand point. Thank you very much.

-Matthew

Hello,

C:\Orthanc>OrthancWSIDicomizer-0.2.exe [\Users\Imaging\Downloads\openslide\bin\libopenslide-0.1.dll] [\Users\Imaging\Downloads\1057056.svs]

E1216 12:22:11.089608 Dicomizer.cpp:895] Terminating on exception: The specified path does not point to a regular file

The error clearly shows that the DICOM-izer is unable to open either OpenSlide, or the source image. I don’t have access to a Windows computer, but there is visibly a problem in the way you specify paths on the command line. The path to OpenSlide should be prefixed with “–openslide”, and backslashes should either be either escaped (i.e. doubled as in “\”) or replaced by forward slashes (i.e. “/”). Furthermore, I don’t think it is possible to use DLL or files from a network share.

I recommend you to first copy the “openslide” folder (available from Downloading OpenSlide) and the source image “1057056.svs” to a local folder, say “C:\Temp”. Then, give a try to the following (untested) command:

C:\Orthanc> OrthancWSIDicomizer-0.2.exe --openslide=C:/Temp/openslide/bin/libopenslide-0.dll C:/Temp/1057056.svs

There is also another open-source WSI DICOM converter software (FFEI Sierra):https://lists.andrew.cmu.edu/pipermail/openslide-users/2014-August/000895.html that uses Openslide and Supplement 145 to convert the proprietary file formats to Dicom, and when I try importing those file to Orthanc I receive the following error:
Error- Cannot get the pyramid structure of series…

Unfortunately, this software is freeware: You can download the binaries, but not the source code. This is not an open-source software. As a consequence, the Orthanc project cannot provide any guidance for it.

HTH,
Sébastien-

Now I have my next problem, the files that I have converted to DICOM using the FFEI openslide to DICOM converter: https://lists.andrew.cmu.edu/pipermail/openslide-users/2014-August/000895.html give me an error (Error - Cannot get the pyramid structure of the series:…) […] It should theoretically convert the files the same was as the DICOMizer you provide, but maybe not. […] Or if I can send you some of the (DCM) files that the FFEI converter exports, maybe you can see why Orthanc cannot identify the pyramid structure.

Back to the FFEI converter, the first thing to try is to run the latest version of the “dciodvfy” from David Clunie’s dicom3tools package [1], in order to check the compliance of the file FFEI generates.

It the file is non-compliant, it is normal that Orthanc cannot process it.

[1] Dicom3tools Software

Thank you so much for your assistance, I was able to successfully get it to work: the Dicomizer seems to only work with the 32-bit openslide dll files, I was using the 64-bit since i have a 64-bit machine. Otherwise the DICOMizer works well, thank you so much for your efforts.

-Matthew

Thank you so much for your assistance, I was able to successfully get it to work: the Dicomizer seems to only work with the 32-bit openslide dll files, I was using the 64-bit since i have a 64-bit machine. Otherwise the DICOMizer works well, thank you so much for your efforts.

Great! Nice to read that the whole-slide imaging framework works for you :slight_smile:

64-bit binaries should be available soon courtesy of Osimis.

Sébastien-

64bit binaries are now included in our Windows packages: http://www.osimis.io/en/download.html