README.TXT - Please Read This File First Before Installing PacsOne Server

Copyright (C) 2003-2023 Rainbowfish Software. All rights reserved.


INTRODUCTION

  PacsOne is a DICOM 3.0 compliant Picture Archive and Communication System
  (PACS) application that consists of the following components:

  1. A DICOM protocol server for servicing requests for image storage, query
     and retrieval.
  2. MySQL database for managing image records and related patient, study,
     series information.
  3. Apache 2.0 HTTP server and PHP scripting engine for presenting a web-based
     user interface for managing database records.
  4. ImageMagick module for displaying images to client's web browsers.

PLATFORMS

  The following platforms are currently supported:

  Windows NT 4.0, Windows 2000 Server, Windows XP, Windows 2003 Server.

INSTALLATIONS

  This package (where this README.TXT file is obtained) requires prior
  installation of MySQL database server.

  The following sections describe detailed guidelines for each specific
  component:

  1. MySQL Database:
    
    The latest released version of MySQL can be downloaded from:

    http://www.mysql.com/downloads/index.html

    NOTE: On Windows NT/2000/XP/2003 platforms, some older releases (version
    3.2.x or earlier) of the MySQL setup program does NOT install MySQL as a
    Windows service automatically.  If this is the case, you need to run the
    following command manually from a command shell to make sure MySQL is 
    installed to run as a Windows service:

    shell> {MySQL Executable Path}\mysqld --install

    where {MySQL Executable Path} is the path to MySQL executables. (e.g.,
    C:\mysql\bin\)

    If the initial password for 'root' is empty, it's recommended to setup a 
    non-empty 'root' password first for security reasons:

      shell>mysqladmin -u root password NEW_PASSWORD

      where NEW_PASSWORD is the new non-empty password for 'root'

    The super-user 'root' username and password are required when running the
    setup program for PacsOne Server and when creating PacsOne Server user
    accounts through the web user interface. Please refer to documentation in
    'doc/install.pdf' for more details.

  2. PacsOne Server:

    After MySQL database has been set up successfully above, PacsOne Server
    can now be installed by downloading this package, and running SETUP.EXE
    and follow the Installation dialog:
    
    - DICOM Specific Configurations:

      APPLICATION ENTITY TITLE:

      This is the Application Entity Title used by PacsOne Server when it
      services requests from other clients or application entities.

      SERVER PORT:

      The TCP port number PacsOne Server listens to.  It's recommended to set
      it to a value larger than 1024 to avoid conflicts with reserved ports.

      LOG FILE DIRECTORY:

      Directory where PacsOne Server writes its log files. The value defaults
      to where PacsOne Server was installed to.

    - MySQL Specific Configurations:

      DATABASE NAME, USERNAME and PASSWORD:

      These are the database name, username and password configured during the
      above MySQL Database installation.

      DROP AND CREATE DATABASE TABLES:

      This checkbox specified whether to drop and create database tables used
      by PacsOne Server.  Selecting this checkbox will delete any existing
      tables and re-create them for use by PacsOne Server.

    - Storage Specific Configurations:

      DEFAULT ARCHIVE DIRECTORY:

      This is the default directory PacsOne Server stores its received images
      if it doesn't know where to store it based on the application entity
      title of the requesting client.  See Section 4 for details about Managing
      the Application Entity table from the web interface.
      
      ARCHIVE FORMAT:

      There're 2 available formats for storing received images.  DICOM Part 10
      (Default) or Native (without Part 10 header).

    Once the above entry fields are configured, press the <Install> button to
    install PacsOne Server.

  3. Apache HTTP Server and PHP Script Engine:

    PacsOne Server has been tested with Apache Web Server 2.0.44 and PHP 4.3.1.

    The latest released version of Apache 2.0 Server can be downloaded from:

    http://httpd.apache.org/download.cgi

    The latest released version of PHP can be downloaded from:

    http://www.php.net/downloads.php

    It's recommended to run PHP as a Apache module instead of CGI executables
    due to both performance and security reasons.

    The following notes provide help about running PHP as a Apache Module:

    - HTTPD.CONF

      This is the main Apache configuration file, the following lines should be
      added or modified in corresponding sections to configure PHP as a Apache
      module:

      ################## BEGIN: HTTPD.CONF ################################

      <.....>
      #
      # Loadable modules
      #
      LoadModule php4_module "{PHP_INSTALL_DIR}/sapi/php4apache2.dll"

      <.....>
      #
      # TypesConfig describes where the mime.types file (or equivalent) is
      # to be found.
      #
      <IfModule mod_mime.c>
        TypesConfig conf/mime.types
        AddType application/x-tar .tgz
        AddType application/x-rar-compressed .rar
        <IfModule sapi_apache2.c>
            AddType application/x-httpd-php .php
            AddType application/x-httpd-php-source .phps
        </IfModule>
      </IfModule>

      <.....>
      #
      # Alias
      #
      Alias /pacsone "{PACSONE_INSTALL_DIR}/php"
      <Directory "{PACSONE_INSTALL_DIR}/php">
        Options Indexes MultiViews
        AllowOverride None
        Order allow,deny
        Allow from all
      </Directory>

      ################## END: HTTPD.CONF ################################

      where:
      
      PHP_INSTALL_DIR is the directory where PHP was installed.
      PACSONE_INSTALL_DIR is the directory where PacsOne Server was installed.

    - PHP.INI

      This is the main PHP configuration file and it should be copied to either
      the Apache installation or %SystemRoot% directory. 

    - PHP4TS.DLL

      The PHP for Apache module (php4apache2.dll above in HTTPD.CONF) depends on
      this DLL, and it should be copied to either the same directory as file
      php4apache2.dll or %SystemRoot%\System32 directory so that it can be
      loaded properly when Apache starts.

    Refer to Apache and PHP documentations for installation instructions and
    configuration details.

  4. ImageMagick PHP Module:

    PacsOne Server uses ImageMagick libraries for displaying stored images as
    converted .JPG or .GIF images to web browsers.  It has been tested with
    ImagicMagick 5.5.6 libraries.  The latest release of ImageMagick can be
    downloaded from:

    http://www.imagemagick.org/

    To configure ImageMagick as a PHP module, the following files need to be
    modified:

    - PHP.INI

      ################## BEGIN: PHP.INI ################################

      ; Directory in which the loadable extensions (modules) reside.
      extension_dir = {PHP_INSTALL_DIR}\extensions
      
      ;Windows Extensions
      extension=php_imagick.dll

      ################## END: PHP.INI ################################
      
      where:

      PHP_INSTALL_DIR is the directory where PHP was installed.
      PACSONE_INSTALL_DIR is the directory where PacsOne Server was installed.

      php_imagick.dll is the module DLL which needs to be copied from:

        {PACSONE_INSTALL_DIR}\php\

      to:

        {PHP_INSTALL_DIR}\extensions\

      After PHP.INI or HTTPD.CONF configuration file is modified, the Apache Web
      Server needs to be re-started for the changes to take effect.

  5. Web User Interface:

    PacsOne Server uses PHP scripts to provide a web-based user interface for
    managing its database records and displaying stored images to web browsers.
    By default, the PHP scripts are installed under:
    
        {PACSONE_INSTALL_DIR}\php

    directory when PacsOne Server package is installed. If the Apache Web
    Server configuration file (HTTPD.CONF in Section 3 above) has been modified
    to provide an alias or virtual document root to the PacsOne Server PHP
    scripts directory above, users can then login to PacsOne database using the 
    following URL from a web browser:

        http://{HOSTNAME}/{ALIAS}/home.php

    where:
	
    HOSTNAME is the name of host where PacsOne Server is installed, for
    example, "localhost" if the web browser is on the same host.

    ALIAS is the Apache HTTP Server Alias created for PacsOne, e.g., "pacsone".

USER's GUIDE

  The following provides a brief description of the PacsOne web user interface:

    - Login Page

      This page will ask the user to enter: Database Name, Username and
      Password and authenticate the user before serving the PacsOne Main Page.
      The Database Name is the name of the database created for PacsOne Server
      in Section 1.  The Username/Password are validated again the MySQL
      Username/Password created in Section 1.  Only users with MySQL Full
      privileges for the specified PacsOne Server database can modify records
      stored in the database.  Users with Read-Only privilege can browse the
      database records and view stored images, but can not modify them.

    - Main Page (Home Link)

      After an user has been authenticated, the PacsOne Server Main Page is
      displayed which list all patients currently in the database along with
      patient related information. The list also has embedded URL links which
      allows user to click and follow to individual Patient Details Page.

    - Patient Details Page

      This page contains detailed information available about an individual
      patient.

    - Study Page

      From the Main Page, user can click on an individual patient to display
      all related studies for this patient along with their study releated 
      information.

    - Series Page

      From the Study Page, user can click on an individual study to display
      all related series for this study along with their series related
      information.

    - Forward Page

      From the Patient, Study or Series Page, a 'Forward' button has been
      added to enable forwarding of all instances of a patient, study or
      series to a remote AE. If the button is clicked, this page will be
      displayed to let user select the detination remote AE from a drop-down
      list.  The remote AE must have been defined in the 'applentity' table
      and must have the IP address/hostname and port number defined. Once the
      forwarding job has been submitted, it will be processed by background
      worker thread within 5 seconds (current polling interval) and the status
      will be updated in the Job Status page.

    - Image Page

      From the Series Page, user can click on an individual series to display
      all related images for this series along with their image releated 
      information. For each image, this page also display a thumbnail image
      in either .JPG and .GIF format.

    - Image Details Page

      From the Image Page, user can click on the embedded thumbnail image to
      display the selected image in full size.

    - Online Image Processing Page

      From this Page, user can select a variety of image processing tools such as:
      Window/Level, Gamma Correction, Contrast, Edge Enhancement, Resize, Noise
      Enhancement, Histogram Equalization, Invert, Normalize and Rotation.

    - Application Entity Page (ApplicationEntity Link)

      This page display a list of known application entities and each record
      contains the following fields:

      Title:        Application Entity (AE) Title.  This field is required.

      Hostname:     Hostname of the remote AE.  This field is optional and it is
                    used to connect to the corresponding C-STORE SCP remote AE
                    when servicing C-MOVE requests.

      IpAddr:       IP address of the remote AE.  This field is optional and it
                    is used to connect to the corresponding C-STORE SCP remove
                    AE when servicing C-MOVE requests.

      Port:         TCP port number of the remote AE.  This field is optional
                    and it is used to connect to the corresponding C-STORE SCP
                    remote AE when servicing C-MOVE requests.

      AllowAccess:  'Enable' or 'Disable' access to PacsOne database for this
                    application entity.  If set to 'Disable', PacsOne server 
                    will reject any association requests with the specified
                    application entity title.  This field is optional and it
                    has the default value of 'Disable'.

      ArchiveDir:   Archive directory for this application entity.  This field
                    is optional and it only applies to C-STORE SCU application
                    entities that send images to PacsOne.

      Directory
      Usage:        If the Archive directory for this application entity is a
                    valid directory, this filed contains the total disk space
                    usage in bytes for all files and folders underneath this
                    directory.

      If the user logged in has FULL privilege to the PacsOne database table,
      this page also provides methods to Add, Delete or Modify entries in the
      Application Entity table.

    - Remote Application Entity Page (Remote AE Link)

      This page display a subset of the all application entities which has the
      IP Address, Hostname and TCP Port Number defined, and each record
      contains the following fields in addition to the common Application
      Entity attributes listed above:

      Verify
      Connection:   Pressing the <Ping> link will initiate a C-ECHO verification
                    request to the remote AE using the corresponding IP address/
                    Hostname and TCP Port. A confirmation message box will be
                    displayed if the remote AE has successfully accepted the
                    C-ECHO verification request, otherwise a detailed error
                    message will be displayed about why the C-ECHO request failed.

      Remote
      Exams:        Pressing the <Query/Retrieve> link will initiate a C-FIND
                    request to the remote AE using the corresponding IP address/
                    Hostname and TCP Port. The C-FIND query results returned from
                    the remote AE will be displayed, as well as a <Move> button
                    to retrieve/move the corresponding patients, studies,series
                    and/or images to a destination AE using the C-MOVE command.
                    If there's any error during either the Query or Retrieve/Move
                    command message, a detailed error message will be displayed
                    indicating why the C-FIND or C-MOVE request failed.

    - Search Page (Search Link)

      This is the main search page where user can search for patient, study or
      series information stored in the PacsOne server database.  The following
      wild-card characters are supported:

      '*': Match one or more characters.
      '?': Match a single character.

      The following search methods are supported:

      Search by Patient:    By Patient ID
                            By Patient Name

      Search by Study:      By Study UID
                            By Study ID
                            By Study Date
                            By Study Accession Number

      Search by Series:     By Series UID
                            By Series Date
                            By Modality

    - Status Page (Job Status Link)

      From this page, users can check the staus of their submitted jobs. For
      example, if the user has forwarded a patient, study or series to a remote
      destination AE, the status of the forwarding job can be checked from this
      page.  This page will display the Completed jobs first followed by
      Pending and Failed jobs. If the status of a job is not 'Completed', any
      specific errors will be displayed in the 'Details' column. 'Failed' jobs
      can be re-submitted via the 'Retry' button. 'Completed' or 'Failed' jobs
      can be deleted via the 'Delete' button and they will be automaically
      deleted from the system after a period of 24 hours.

    - Logout Page (Logout Link)

      Selecting this link will logout the active user from current session, and
      re-direct client browser back to the Login Page.

  Please refer to 'doc/manual.pdf' for more details.

CONTACTS

  For general comments, suggestions, ideas, send emails to:

    mailto:pacsone@rainbowfishsoftware.com

  For feature requests, send emails to:

    mailto:feature.request@rainbowfishsoftware.com

  For bug reports, send emails to:

    mailto:bug.report@rainbowfishsoftware.com

  For PacsOne users bulletin board:

    http://www.pacsone.net/forum/

  For commercial licensing information:

    mailto:licensing.info@rainbowfishsoftware.com

COPYRIGHTS

  PacsOne Server uses the JPEG compression/de-compression libraries developed
  by the Independent JPEG Group (IJG).

