--[[
	This grouping script partition nuclear medicine (NM) images as follows:
	Scout images in their own sequences
	Group all other images by a combination of DICOM Series instance UID, 
	view prop, series number and phase.   
   
	Cristian Bonciu	August-September 2004
	-	Created/implemented the functionality from pseudo-code prototypes provided by Allan 
	Mahesh Nagarajan		18 JAN 2006	
     -	Added sort hint for ID SOP Instance UID just before filename
	Mahesh Nagarajan		08 FEB 2006
     -	Added "All Images" functionality
	Mahesh Nagarajan		07 JULY 2006
     -	Turns out that some NM modalities do not send the images with the (0002, 0013)
		META Version Info Name tag, which in turn fails to create the "All Images"
		sequence.  To ensure that the "All Images" is always created, the grouping hint for 
		this sequence is set to modality if the META tag is unavailable.
	Mahesh Nagarajan		01 FEB 2007
	-	MAJOR SCRIPT REVAMP; please compare with earlier version on VSS if necessary
	-	Implemented support for user controlled sorting on multiple attributes using prototypes 
		from Mike McFarland. For more details on the sequencing engine changes, please consult 
		the document titled "Lua Application Programming Interface for Multiple Sorting Criteria 
		Sequencing. The corresponding FEATs for HRS are FEAT219 and FEAT250.	
	- 	Modified syntaxes for grouping and sorting hints as part of v11.5 re-write
	-	"All Images" will no longer be created in the sequencing scripts; HRS will take 
		responsibility for generating this sequence
	Mahesh Nagarajan		17 MAY 2007
	-	Removed the modality prefix and sort suffix from sort names as it looked stupid
	Mahesh Nagarajan		28 MAY 2007
	- 	Bringing back the "All Images" sequence until the corresponding HRS feature gets 
		implemented; this will get one sort order called "Default"
	Mahesh Nagarajan		05 JUN 2007		
	-	Must split still multi-frame sequences into seperate sequence; such images are
		unreadable otherwise.
	Mahesh Nagarajan		17 JUN 2008
	-	Modified the sorting of the "all images" sequence and the thumbnails to (1) ensure
		similar sorting for both and (2) change primary sorting to file name
	Mahesh Nagarajan		31 MAR 2008
	-	Splitting NM derived images into a single image per series for IRMC	
	Shudong Liu    Feb. 18, 2009
	- 	Removed "*All Images*" sequence for HMI 11.6	
--]]

-- Enable tracing in this module for debugging (comment out for production version)
-- AliDSTraceLevel = 2 

function RegisterSortingHintTypes( )
-- ////////////////////////////////////////////////////////////////////////////
-- This function will register the various sort orders that are created for NM
-- ////////////////////////////////////////////////////////////////////////////
    RegisterHintType( "ACQUISITION TIME SORT", "Acquisition Time" )
	RegisterHintType( "IMAGE NUMBER SORT", "Image Number" )
    RegisterHintType( "FILE NAME SORT", "File Name" )
    RegisterHintType( "DEFAULT SORT", "Default" )
end

function Execute()
-- ////////////////////////////////////////////////////////////////////////////
-- generates the hints for the sequencer as follows 
-- add IMAGE_TYPE as the grouping hint when its value is one (scout image)
-- for all other use multiple hints like series UID, view, series number, and phase 
-- ////////////////////////////////////////////////////////////////////////////

   TraceC("Group NM executing\n")
   
    -- If this is the wrong script for the supplied image...
    if (not SanityOK("NM")) then
      return nil
      -- =====================================================
    end
    
	-- MaxN: Note that the default sort for NM is by acquisition time; so we do not
	-- have a seperate "default" sort scheme like we did for CT & MR. 
   	local sortHint01 = SortingHint:new( "Acquisition Time", "ACQUISITION TIME SORT" )
    sortHint01:AddEntry(ACQUISITON_DATETIME_TAG, true)
    sortHint01:AddEntry(ACQUISITON_DATE_TAG, true)
    sortHint01:AddEntry(ACQUISITON_TIME_TAG, true)
    sortHint01:AddEntry(IMAGE_ACQUISITON_TIME_TAG, true)
    sortHint01:AddEntry(INSTANCE_NUMBER_TAG, true)
    sortHint01:AddEntry(IMAGE_UID_TAG, true)
    sortHint01:AddEntry(ALI_IMAGE_FILENAME_TAG, true)
	
	-- Create a "Sort Hint Set" here; all alternate sorts will be added to this one if they are created
	local sortHintSet01 = SortingHintSet:new( )
	sortHintSet01:AddHint( sortHint01, true )
	
	-- Creating an image number sort for NM - created only if (0020, 0013) REL Image Number exists
	if (HasAttr(INSTANCE_NUMBER_TAG)) then
		local sortHint02 = SortingHint:new( "Image Number", "IMAGE NUMBER SORT" )
		sortHint02:AddEntry( INSTANCE_NUMBER_TAG, true ) 
		
		-- If we are here, then the image number sort was created successfully; adding it to the sort hint set for NM
		sortHintSet01:AddHint( sortHint02 )
	end
	
	-- Not checking for file name as it should always exist
	local sortHint03 = SortingHint:new( "File Name", "FILE NAME SORT" )
	sortHint03:AddEntry( ALI_IMAGE_FILENAME_TAG, true )
	sortHintSet01:AddHint( sortHint03 )
    
    TraceC( "Group NM sort hints created.\n")

	local groupHint01 = GroupingHint:new( ValueForTag( SERIES_DESC_PROP, "?" ) )

	if( HasAttr(SERIES_UID_TAG) ) then
        TraceC("Grouping hint: series UID\n")
        groupHint01:AddEntry(SERIES_UID_TAG)
    end
    
    if( HasAttr(NM_IMAGE_TYPE_PROP) ) then
        TraceC("Grouping hint: NM image type property\n")
        groupHint01:AddEntry(NM_IMAGE_TYPE_PROP)
    end
    
    if( HasAttr(VIEW_PROP) ) then
        TraceC("Grouping hint: view property\n")
        groupHint01:AddEntry(VIEW_PROP)
    end
	
    if( HasAttr(PHASE_PROP) ) then
        TraceC("Grouping hint: phase property\n")
        groupHint01:AddEntry(PHASE_PROP)
    end
	
	--$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
	-- For site IRMC, splitting by image UID if image type is derived
	local SiteName = GetAttr(INSTITUTION_NAME_TAG)
	if (SiteName~=nil and BestWordMatchInAttr(SiteName, "IRMC")) then
		if ( ValueForTag(IMAGE_TYPE_TAG) == "DERIVED" ) then
			TraceC("Grouping hint: image UID tag\n")
			grpHint:AddGroupHint(IMAGE_UID_TAG) 
		end
	end
	--$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$

	-- Must check if the still image is multi-frame; if so, it should be split 
	-- into a seperate thumbnail
	local nFrames = ValueForTag(NUMBER_OF_FRAMES_TAG)
	if (nFrames and nFrames > 1) then
        TraceC("Grouping hint: image UID tag\n")
		groupHint01:AddEntry(IMAGE_UID_TAG) 
	end
	
    AddImage2Sequence( "NM Sequence", groupHint01, sortHintSet01 )
	
    TraceC( "Group NM execution complete.\n")

end

