; ========================================================================= ;+ ; PROJECT: ; Solar-B / XRT ; ; NAME: ; SAO_WRITE_MPEG ; ; CATEGORY: ; Input/Output ; ; PURPOSE: ; A wrapper to provide a simpler interface for writing MPEGs. ; ; CALLING SEQUENCE: ; SAO_WRITE_MPEG, filename, image_cube [, bitrate=bitrate] ; [, /color] [, iframe_gap=iframe_gap] ; [, motion_vec_length=motion_vec_length] [, quality=quality] ; [, /verbose] [, qfail=qfail] ; ; INPUTS: ; FILENAME: [Mandatory] String scalar. ; Set this keyword to a string representing the name of ; the file to which the encoded MPEG sequence is to be ; saved. (No default.) ; ; IMAGE_CUBE: [Mandatory] ; Array [image xsize, image ysize, number images]. ; - The number of image pixels, xsize*ysize, *must* ; be an even number.) ; - Since the values will be passed through a ; color table, decimals will be dropped. ; - Also for color table reasons, values less than ; 0 will be set to 0, and values greater than 255 ; will be set to 255. ; ; KEYWORDS: ; BITRATE: [Optional] Double floating-point scalar. ; Specifies the MPEG movie bit rate. ; - Higher bit rates will create higher quality MPEGs ; but will increase file size. ; - Only use BITRATE if changing the QUALITY value does ; not produce the desired results. ; - It is highly recommended to set the BITRATE to at ; least several times the frame rate to avoid unusable ; MPEG files or file generation errors. (NB: Frame rate ; is not adjustable with this program, but may be ; adjusted with the IDL MPEG object model.) ; 0: Indicates that IDL should compute the BITRATE value ; based upon the value you have specified for the ; QUALITY keyword. Computed value is returned. ; (Default.) ; (0.1 to 104857200.0): Valid range for BITRATE. ; ; /COLOR: [Optional] Boolean switch. ; 0: Standard grayscale, where 0=black, 255=white. ; (Default.) ; 1: Read color table from IDL environment. ; To set a color table, use , , ; etc. before calling SAO_WRITE_MPEG. ; ; IFRAME_GAP: [Optional] Positive integer scalar. ; Specifies the number of frames between I-frames to be ; created in the MPEG file. I-frames are full-quality ; image frames that may have a number of predicted or ; interpolated frames between them. ; - Only use the IFRAME_GAP keyword if changing the ; QUALITY value does not produce the desired results. ; 0: Indicates that IDL should compute the IFRAME_GAP ; value based upon the value you have specified for ; the QUALITY keyword. Computed value is returned. ; (Default.) ; 1+: Number of frames between I-frames to be created ; in the MPEG file ; ; MOTION_VEC_LENGTH: [Optional] Restricted integer scalar. ; Specifies the length of the motion vectors to be used ; to generate predictive frames. ; - Only use the MOTION_VEC_LENGTH keyword if changing ; the QUALITY value does not produce the desired ; results. ; 0: Indicates that IDL should compute the ; MOTION_VEC_LENGTH value based upon the value you ; have specified for the QUALITY keyword. Computed ; value is returned. (Default.) ; 1: Small motion vectors. ; 2: Medium motion vectors. ; 3: Large motion vectors. ; ; QUALITY: [Optional] Restricted integer scalar. ; Specifies the quality at which the MPEG stream is to be ; stored. ; - Higher quality values result in lower rates of time ; compression and less motion prediction which provide ; higher quality MPEGs but with substantially larger ; file size. ; - Lower quality factors may result in longer MPEG ; generation times. ; - The default is 50. ; - Since MPEG uses JPEG (lossy) compression, the original ; picture quality cannot be reproduced even when setting ; QUALITY to its highest setting. ; 0: QUALITY value is set to 50. (Default.) ; (1-100): Higher = less compression and larger files. ; ; /VERBOSE: [Optional] Boolean switch. ; 0: No debugging info printed to display. ; 1: Debugging info printed to display. ; - On a successful run, VERBOSE=1 will print the total ; program runtime. ; ; QFAIL: [Optional] Boolean scalar. ; If SAO_WRITE_MPEG is being called from a superroutine, ; the returned value of QFAIL indicates if SAO_WRITE_MPEG ; had to abort prematurely for inadequate inputs. ; 0: No input errors were discovered. ; 1: An input error was discovered. ; - If (QFAIL eq 1) as *input*, SAO_WRITE_MPEG will ; immediately abort and return. ; ; OUTPUTS: ; Writes MPEG movie with filename. ; ; EXAMPLES: ; 1) Write as a B&W MPEG named "image_cube.mpg". ; IDL> sao_write_mpeg, 'image_cube.mpg', image_cube ; ; 2) Write as a color MPEG, using a standard ; color-table. ; IDL> xloadct ;; Pick a color table. ; IDL> sao_write_mpeg, 'image_cube.mpg', image_cube, /color ; ; 3) Write as a color MPEG, using a designed ; color-table (rr, gg, bb). ; IDL> tvlct, rr, gg, bb ; IDL> sao_write_mpeg, 'image_cube.mpg', image_cube, /color ; ; 4) Write as a color MPEG, at the highest quality, ; using a designed color-table (rr, gg, bb). ; IDL> tvlct, rr, gg, bb ; IDL> sao_write_mpeg, 'image_cube.mpg', image_cube, /color, $ ; IDL> quality=100 ; ; COMMON BLOCKS: ; None. ; ; NOTES: ; 1) This program uses MPEG_OPEN.PRO, which only accesses a ; subset of IDL's MPEG object properties. One must use IDL's ; MPEG object model to affect those other properties. ; 2) This program uses MPEG1 level encoding. MPEG2 level is ; only available in the MPEG object model. ; 3) This program uses "non-interlacing". "Interlacing" is only ; available in the MPEG object model. ; 4) User must scale their data *before* calling SAO_WRITE_MPEG. ; This program assumes that data values correspond to an 8-bit ; color-table (0-255), and will truncate values outside this ; range. It is up to the user to work out how to scale their ; data. ; 5) When creating MPEG files, you must be aware of the ; capabilities of the MPEG decoder you will be using to view it. ; Some decoders only support a limited set of sampling and ; bitrate parameters to normalize computational complexity, ; buffer size, and memory bandwidth. For example, the Windows ; Media Player supports a limited set of sampling and bitrate ; parameters. In this case, it is best to use 352 x 240 x 30 fps ; or 352 x 288 x 25 fps when determining the dimensions and ; frame rate for your MPEG file. When opening a file in Windows ; Media Player that does not use these dimensions, you will ; receive a "Bad Movie File" error message. The file is not ; "bad", this decoder just doesn't support the dimensions of the ; MPEG. ; ; MODIFICATION HISTORY: ; 2006.02.09 --- (M. Weber) Written. ; 2006.02.10 --- (M. Weber) Added BITRATE, IFRAME_GAP, QUALITY, ; and MOTION_VEC_LENGTH keywords. ;- ; =========================================================================