workspace.h

#ifndef __WORKSPACE_H__
#define __WORKSPACE_H__
/*=============================================================================   
   Module  : workspace.h 
   Purpose : Include file for managing the workspace which is the main
             structure in the program.
   Author  : Doug Ehlenberger, CNIC Mt. Sinai School of Medicine
             
=============================================================================*/
#include "configure.h"
#include "prjmgrfuncs.h"
#include "projectionmgr.h"
#include "imagestackmgr.h"
#include "handle.h"
#include "imagerw.h"
#include "progress.h"
#include "vectori.h"
#include "imalign.h"


/* IMPORTANT!!!

   COORDINATE SYSTEMS( for the workspace and the window( client ) ) 


   NOTE: Workspace coordinates are a right hand coordinate system rotated 
         180 degrees around x-axis. 

         ( '+' indicates positive axis if "traveling" from the origin 
           out along the axis. )

             / +Z
            /
           /
          /--------- +X
          |
          |
          |
          | +Y


   In forward view:


          ----------  +X              ----------  +X
          |                           |
          |                           |
          |                           |
          | +Y                        | +Y

         client( window )            workspace


   In side view:

          ----------  +X              ----------- +Z  
          |                           |
          |                           |
          |                           |
          | +Y                        | +Y

         client                     workspace


   In top view:

          ----------  +X              ----------- +X
          |                           |
          |                           |
          |                           |
          | +Y                        | -Z

         client                     workspace

   NOTE: The -Z for the top view!! This could be avoided by assuming the view was
   from the bottom but it is more intuitive to view the volume from the top. The 
   current view will have to be known and certain operations will have to change 
   when in top view.
*/


/* View types, i.e. which set of projections are being viewed. */

typedef enum
   {
   vVWS_VIEW_FORWARD = vPROJ_Z,
   vVWS_VIEW_SIDE    = vPROJ_X,
   vVWS_VIEW_TOP     = vPROJ_Y
   }
   vVWS_VIEW_TYPE;


typedef enum
   {
   /* Left and right can range from 0 to width of stack - 1.
      NOTE: right must be > left */                             
   vCROP_LEFT,                                          
   vCROP_RIGHT,                                         
                                                        
   /* Bottom and top can range from 0 to height of stack - 1. 
      NOTE: bottom must be > top */                           
   vCROP_TOP,                                           
   vCROP_BOTTOM,                                        
                                                        
   /* Near and far can range from 0 to length( i.e. number of files ) of stack - 1. 
      NOTE: far must be > near */   
   vCROP_NEAR,
   vCROP_FAR
   }
   vCROP_TYPE;


/* Structure to retrieve info. on a stack's projection for drawing. See 
   function GetImageStackProjection() below. */


typedef enum
   {
   vVWS_NO_ERROR,
   vVWS_ERROR_OUT_OF_MEMORY,
   vVWS_ERROR_INVALID_VWS_DIR,
   vVWS_ERROR_INVALID_STACK_DIR,
   vVWS_ERROR_INVALID_VWS_FNAME,
   vVWS_ERROR_WORKSPACE,
   vVWS_ERROR_STACK_PROPERTIES,
   vVWS_ERROR_REMOVE,
   vVWS_ERROR_INVALID_FILTER,

   vVWS_ERROR_PROJ_OUT_OF_MEMORY,
   vVWS_ERROR_PROJ_MISMATCH_PIXELS,
   vVWS_ERROR_PROJ_MISMATCH_DIMENSIONS,
   vVWS_ERROR_PROJ_MULTIPLE_FILE_TYPES,
   vVWS_ERROR_PROJ_FILE_OPEN,
   vVWS_ERROR_PROJ_FILE_READ,
   vVWS_ERROR_PROJ_FILE_WRITE,
   vVWS_ERROR_PROJ_FILE_INVALID,
   vVWS_ERROR_PROJ_FILE_TYPE,
   vVWS_ERROR_PROJ_UNSUPPORTED,
   vVWS_ERROR_PROJ_FUNCTION,
   vVWS_ERROR_PROJ_HANDLE,

   vVWS_ERROR_FILE_LIST_NO_FILES,
   vVWS_ERROR_FILE_LIST_INVALID_SPEC,
   vVWS_ERROR_FILE_LIST_OUT_OF_MEMORY,

   vVWS_ERROR_NEW_VWS_DIR_EXISTS,
   vVWS_ERROR_NEW_VWS_DIR_PATH,

   vVWS_ERROR_INTERNAL,

   vVWS_ERROR_VWS_DIR_PATH_LENGTH,

   vVWS_ERROR_READ_CUBE_PIXEL_CODE,
   vVWS_ERROR_CREATE_CUBE_PIXEL_CODE,

   vVWS_ERROR_STACK_HANDLE,
   
   vVWS_ERROR_MULTIPLE_2D_3D,

   vVWS_ERROR_SENTINEL
   }
   vVWS_ERROR_CODE;


#define vNUM_VWS_ERROR_CODES            ( ( vINT )vVWS_ERROR_SENTINEL )
#define vWORKSPACE_PROGRESS_CANCEL     vVWS_ERROR_SENTINEL
#define vWORKSPACE_FILE_EXTENSION      ".vws"


typedef struct tagVOXELSARGS
   {
   vUNITS_TYPE  units;
   vFLOAT       spacingX;
   vFLOAT       spacingY;
   vFLOAT       spacingZ;
   }
   VOXELSARGS;

#define vDEFAULT_VOXEL_UNITS       vUNITS_MICRONS
#define vDEFAULT_VOXEL_SPACING_X   1.0f
#define vDEFAULT_VOXEL_SPACING_Y   vDEFAULT_VOXEL_SPACING_X
#define vDEFAULT_VOXEL_SPACING_Z   vDEFAULT_VOXEL_SPACING_X


typedef struct tagWorkspace
   {
   ProjectionManager  *projectionManager;  
   ImageStackManager  *imageStackManager;

   /* Store the handles to the image stacks. */
   vHIMAGESTACK       *imageStacks;            
   /* Full size of the array. */
   vSIZE               imageStackCapacity;         
   /* Number of array indices actually being used. */
   vSIZE               numStacks;  

   /* Store which stacks have been "selected" by the user 
      for some type of manipulation. */
   vHIMAGESTACK       *selectedStacks;
   vSIZE               numSelectedStacks; 

   /* Which stack selected for cropping. */
   vHIMAGESTACK        hCropStack;

   /* Pixel format for this workspace. */
   vPIXEL_CODE_TYPE    pixelCode;

   /* Voxel spacing and units for this workspace. */
   VOXELSARGS          voxels;
   
   /* Used to assign a unique number to projection file names
      and stack descriptions. */
   vINDEX              uniqueIndex;

   /* Various attributes. */
   vUINT               backgroundColor;
   vUINT               selectedStackBorderColor;
   vUINT               gridLineColor;
   vUINT               gridPointColor;
   vUINT               gridIsVisible;
   vINT                gridStep;
   vUINT               gridFlags;
   vUINT               gridLineStyle;
   vUINT               gridPointSize;

   /* Directory and file name of this workspace. */
   vCHAR               directory[ vMAX_PATH ];
   vCHAR               fileName[ vMAX_PATH ];
   }
   Workspace;


/* Added 4/24/03 */
#define vVWS_DEFAULT_BACKGROUND_COLOR              0xCCCCCC
#define vVWS_DEFAULT_SELECTED_STACKS_BORDER_COLOR  0xFF0000
#define vVWS_DEFAULT_GRID_LINE_COLOR               0x999999
#define vVWS_DEFAULT_GRID_POINT_COLOR              0


/* Long string is the full name of the units, e.g. microns. 
   Short string is the abbreviation for the units, e.g. um. */
vSTRING GetVoxelUnitsLongString( vUNITS_TYPE type );
vSTRING GetVoxelUnitsShortString( vUNITS_TYPE type );


/* Call before any other functions! */
vVWS_ERROR_CODE InitWorkspace( Workspace *vws );

/* Frees all the memory used by the workspace. */
vVOID DestroyWorkspace( Workspace *vws );


/* The OpenWorkspace() function runs as a thread 
   and updates a progress bar dialog. See progress.h 
   for how the error code is set. */
DERIVE_PROGRESSPROCARGS( OPENWORKSPACEARGS, 
                         vUINT      hwndVisual;
                         Workspace *vws; 
                         vSTRING    fullPath; 
                       );

vVOID OpenWorkspace( vVOID *openWorkspaceArgs );


/* Saves the workspace to it's directory. */
vVWS_ERROR_CODE SaveWorkspace( Workspace *vws );

/* Full path is the location of the .vws file. */
vVWS_ERROR_CODE NewWorkspace( Workspace *vws, vSTRING fullPath );


/* Use this function when adding new image stacks to an OPEN workspace. 
   Full path is one file name from the stack. Pass the handle to the
   window where the projections will be shown. The function launches a 
   progress bar dialog and a thread for the creation of the projections. 
   See also projectionmgr.h. A handle to the newly created stack is 
   return in the hSaveHandle parameter. */

vVWS_ERROR_CODE CreateImageStack
   ( 
   Workspace    *vws,
   vUINT         hwndVisual, 
   vSTRING       fullPath, 
   PROGRESSBAR  *progressBar, 
   vHIMAGESTACK *hSaveHandle,
   const ImageDescriptor *descriptor
   );


/* Returns a valid handle if hStack is a duplicate stack. */
vHIMAGESTACK GetDuplicateImageStack( Workspace *vws, vHIMAGESTACK hStack );

/* Some accessor functions. */
vSIZE GetNumImageStacks( Workspace *vws );
vSIZE GetNumSelectedStacks( Workspace *vws );
vSTRING GetWorkspaceDirectory( Workspace *vws );
vSTRING GetWorkspaceFileName( Workspace *vws );

/* "fullPath" buffer must be of at least _MAX_PATH size! */
vVOID GetWorkspaceFullPath( Workspace *vws, vSTRING fullPath );

vFLOAT GetWorkspaceVoxelSpacing( Workspace *vws, vDIM_TYPE which );
vVOID SetWorkspaceVoxelSpacing( Workspace *vws, vDIM_TYPE which, vFLOAT spacing );

/* Get the view dependent voxel spacings. i.e. which spacings correspond to the 
   current client X and Y axis. See coordinate transformations above. */
vVOID GetViewDependentVoxelSpacing
   ( 
   Workspace      *vws, 
   vVWS_VIEW_TYPE  viewType, 
   vFLOAT         *spacingX, 
   vFLOAT         *spacingY 
   );

vUNITS_TYPE GetWorkspaceVoxelUnits( Workspace *vws );
vVOID SetWorkspaceVoxelUnits( Workspace *vws, vUNITS_TYPE type );

vPIXEL_CODE_TYPE GetWorkspacePixelCode( Workspace *vws );


/* Added function 04/21/03. */
vUINT GetImageStackProjectionsReferenceCount( Workspace *vws, vHIMAGESTACK hStack );


/* Index into the workspace's image stacks array. */
vHIMAGESTACK GetImageStackHandle( Workspace *vws, vINDEX index );

/* Index into the workspace's selected stacks array. */
vHIMAGESTACK GetSelectedStackHandle( Workspace *vws, vINDEX index );

/* Access the structure from a handle. */
ImageStack* GetImageStack( Workspace *vws, vHIMAGESTACK hStack );


/* Simple selection and deselection functions. NOTE: For SelectImageStack()
   no check is made whether stack is visible, etc... */
vVOID SelectImageStack( Workspace *vws, vHIMAGESTACK hStack );

vVOID DeselectImageStack( Workspace *vws, vHIMAGESTACK hStack );
vVOID DeselectAllImageStacks( Workspace *vws );

vBOOL ImageStackIsSelected( Workspace *vws, vHIMAGESTACK hStack );

vBOOL ImageStackIsInverted( Workspace *vws, vHIMAGESTACK hStack );
void ImageStackSetInverted( Workspace *vws, vHIMAGESTACK hStack, vBOOL is_inverted );


/* Determine if the stack is recorded in the workspace(.vws) file. */
vBOOL ImageStackIsOnFile( Workspace *vws, vHIMAGESTACK hStack );


/* Get the CURRENT position of the stack. */
vVOID GetImageStackPosition( Workspace *vws, vHIMAGESTACK hStack, Vector3i *position );
/* Save the CURRENT position of the stack. */
vVOID SaveImageStackPosition( Workspace *vws, vHIMAGESTACK hStack );
/* Swaps the old and current positions of the stack. */
vVOID SwapImageStackPositions( Workspace *vws, vHIMAGESTACK hStack );


/* NEW */
vVOID SetImageStackPosition( Workspace *vws, vHIMAGESTACK hStack, const Vector3i *const position );


/* Added functions 4/21/03. */
const vCHAR* GetImageStackSourceDirectory( Workspace *vws, vHIMAGESTACK hStack );
const vCHAR* GetImageStackFileFilter( Workspace *vws, vHIMAGESTACK hStack );


/* Similar to above functions. */
vSIZE* GetImageStackCropCube( Workspace *vws, vHIMAGESTACK hStack );
vVOID SaveImageStackCropCube( Workspace *vws, vHIMAGESTACK hStack );
vVOID SwapImageStackCropCubes( Workspace *vws, vHIMAGESTACK hStack );


vVOID CopyImageStackCropCube( Workspace *vws, vHIMAGESTACK hStack, vHIMAGESTACK hCopy ); /* NEW */


/* Get the FULL dimensions of the stack. */
vSIZE* GetImageStackDimensions( Workspace *vws, vHIMAGESTACK hStack );


typedef struct tagDimensions3D
   {
   vSIZE width;
   vSIZE height;
   vSIZE length;
   }
   Dimensions3D;


/* 'full' and/or 'cropped' can be NULL. */

void GetImageStackFullAndCroppedDimensions3D
   (
   Workspace *const     vws,
   const vHIMAGESTACK   hStack,
   Dimensions3D *const  full,
   Dimensions3D *const  cropped
   );


/* Functions to set and query the visibility of an image stack. */
vVOID SetImageStackVisibility( Workspace *vws, vHIMAGESTACK hStack, vBOOL isVisible );
vBOOL ImageStackIsVisible( Workspace *vws, vHIMAGESTACK hStack );

/* Added functions 5/8/03 */
vVOID SetImageStackPositionLocked( Workspace *vws, vHIMAGESTACK hStack, vBOOL isLocked );
vBOOL IsImageStackPositionLocked( Workspace *vws, vHIMAGESTACK hStack );


/* The first index in the selected stacks array is the crop stack. */
vVOID SetSelectedCropStack( Workspace *vws );
vHIMAGESTACK GetSelectedCropStack( Workspace *vws );
vVOID ClearSelectedCropStack( Workspace *vws );
vBOOL IsSelectedCropStack( Workspace *vws, vHIMAGESTACK hStack );


/* Get/Set the opacity of the stack. */
vUINT GetImageStackAlphaValue( Workspace *vws, vHIMAGESTACK hStack );
vVOID SetImageStackAlphaValue( Workspace *vws, vHIMAGESTACK, vUINT alpha );


/* Get/Set the current client rectangle of this image stack. */
vVOID GetImageStackClientRect( Workspace *vws, vHIMAGESTACK hStack, vRECTANGLE *client );
vVOID SetImageStackClientRect( Workspace *vws, vHIMAGESTACK hStack, vRECTANGLE *client );


/* Get/Set the image stack's description string. */
vSTRING GetImageStackDescription( Workspace *vws, vHIMAGESTACK hStack );
vVOID SetImageStackDescription( Workspace *vws, vHIMAGESTACK hStack, vSTRING description );


/* Depending on the view, get the "topmost" stack by passing a point 
   in WORKSPACE coordinates! Returns a handle to the stack on success 
   or a null handle if no stack at that point. */
vHIMAGESTACK GetStackAtPoint( Workspace *vws, Vector2i point, vVWS_VIEW_TYPE viewType );

/* If a stack at the point, ALL other stacks are deselected first before the stack
   becomes selected. Returns vTRUE on success, else vFALSE. */
vBOOL SelectStackByPoint( Workspace *vws, Vector2i point, vVWS_VIEW_TYPE viewType );


/* This function just marks the stacks in the array as deleted but does NOT actually 
   perform any clean up of the stacks such as freeing memory, deleting files, etc... 
   The handles in the array MUST also be stored in the workspace handle array since
   they will be removed from the workspace handle array. */
vVOID DeleteImageStacks( Workspace *vws, vHIMAGESTACK *stacks, vSIZE numStacks );

/* The handles passed in the array MUST have previously obtained from the workspace's
   handle array. Therefore the workspace handles array is assumed to be of a large
   enough size to hold all the handles. The handles in the array MUST NOT also be stored 
   in the workspace handle array since they will be added to the workspace handle array. */
vVOID RestoreImageStacks( Workspace *vws, vHIMAGESTACK *stacks, vSIZE numStacks );

/* Remove the stack(s) projections from the workspace directory. The handle(s) MUST NOT also be
   stored in the workspaces handle array. */
vVWS_ERROR_CODE RemoveImageStackProjections( Workspace *vws, vHIMAGESTACK hStack );
                          
/* Free all memory used by the image stack structure(s). The handle(s) MUST NOT also be stored in
   the workspaces handle array. */
vVOID ReleaseImageStack( Workspace *vws, vHIMAGESTACK hStack );


/* Based on what the view is, a new crop cube is computed for the
   NOTE: The parameters left, right, top, bottom are in WORKSPACE 
   coordinates and therefore are treated as "offsets" from the stack's 
   current position. Right and bottom should not be "past the end" values.
   
   e.g. cropping a stack in forward view with X width of 1024. For simplicity 
   say that the stack's current position X value is 0 and the crop cube is being 
   set to the full X width of the stack. Then left should be 0 and right should 
   be 1023, NOT 1024!! */
vVOID CropImageStack
   ( 
   Workspace      *vws, 
   vHIMAGESTACK    hStack,
   vCOORD          left, 
   vCOORD          top, 
   vCOORD          right, 
   vCOORD          bottom,
   vVWS_VIEW_TYPE  viewType
   );


/* Translates all the selected stacks by the parameter. NOTE: Which coordinates 
   are affected is determined by the view type. 
   
   vVWS_VIEW_FORWARD : x and y 
   vVWS_VIEW_SIDE    : z and y 
   vVWS_VIEW_TOP     : x and z 

   Returns TRUE if any stacks moved. They could all be locked in which case the
   function will return FALSE.
*/
vBOOL TranslateAllSelectedStacks( Workspace *vws, Vector2i offset, vVWS_VIEW_TYPE viewType );


/* See ImageStackProjection structure declaration above. */
vVOID GetImageStackProjection
   ( 
   Workspace             *vws, 
   vHIMAGESTACK           hStack, 
   vVWS_VIEW_TYPE         viewType,
   ImageStackProjection  *isp 
   );


/* Depending on the view type, sort the stack's so that if staring down an
   axis, the stacks that are closer to the eye are in front. For example in
   the forward view, the eye is looking down the positive Z axis, so given
   two stacks, the one with the lesser Z value should be drawn on "top" of
   the other one. */

vVOID SortImageStacks( Workspace *vws, vVWS_VIEW_TYPE viewType );



#define vAUTO_ALIGN_NUM_STACKS          1
#define vAUTO_ALIGN_DEFAULT_OVERLAP   100

/* NOTE: Currently can only align 1 stack. 
   The stack is aligned to the "anchor" stack. */

typedef struct tagAutoAlignStack
   {
   Image_t   image_t;
   IMAGEA    image_a;  /* See imalign.h */
   Vector2i  position;
   Vector3i  alignedCoord;
   }
   AutoAlignStack;

typedef struct tagAutoAlignment
   {
   vVWS_VIEW_TYPE  viewType;
   vSIZE           overlap;
   AutoAlignStack  stacks[ vAUTO_ALIGN_NUM_STACKS ];
   AutoAlignStack  anchor;
   }
   AutoAlignment;


/* Init. the necessary information BEFORE calling AutoAlignImageStacks(). */

vVWS_ERROR_CODE SetupAutoAlignment
   ( 
   Workspace      *vws, 
   vVWS_VIEW_TYPE  viewType, 
   vINT            overlap,
   vHIMAGESTACK    hAnchor,
   AutoAlignment  *autoAlign
   );


/* Depending on the view type, automatically align stack projections.
   The number of selected stacks MUST be equal to above constant. NOTE: The
   function runs as a thread and updates a progress bar dialog. */

DERIVE_PROGRESSPROCARGS( AUTOALIGNARGS, 
                         Workspace      *workspace;
                         AutoAlignment  *autoAlign;
                       );

vVOID AutoAlignImageStacks( vVOID *autoAlignArgs );


/* Call on SUCCESS of alignment procedure to set the new stack coordinates. */

vVOID SetAlignedImageStackCoords( Workspace *vws, AutoAlignment *autoAlign );


/* Call to free any memory used in the structure. */

vVOID CleanupAutoAlignment( AutoAlignment *autoAlign );


/* Auto-align the workspace for the current view. 
AutoAlignWorkspace();*/

/* Auto-align the workspace for all views. 
AutoAlignEntireWorkspace();*/


#endif /* __WORKSPACE_H__ */

---