RASPISTILL(1)

NAME
raspistill - takes still JPEG captures with the Pi Camera Module

SYNOPSIS
raspistill [-3d mode] [-3dswap] [-a flags|text] [-ae size,fg,bg] [-ag value] [-awb mode] [-awbg b,r] [-bm] [-br value] [-cfx u:v] [-co value] [-cs camera] [-d ms] [-dec] [-dg value] [-dn screen] [-drc value] [-dt] [-e format] [-ev value] [-ex mode] [-f] [-fli mode] [-fp] [-fs num] [-g] [-gc] [-gps] [-gs scene] [-gw x,y,w,h] [-h size] [-hf] [-ifx effect] [-ISO value] [-k] [-l filename] [-md mode] [-mm mode] [-n] [-o filename] [-op opacity] [-p x,y,w,h] [-q quality] [-r] [-roi x,y,w,h] [-rot value] [-rs num] [-s] [-sa value] [-set] [-sh value] [-ss value] [-st] [-t ms] [-th x:y:q] [-tl ms] [-ts] [-v] [-vf] [-w size] [-x key=value]
raspistill [-?]
raspistill [--help]

DESCRIPTION
raspistill is a command line utility for capturing still images from the Raspberry Pi Camera Module (any version). It has numerous options which can be used to customize the capture process, the preview display, or to perform more complex operations like time-lapse or triggered captures.

OPTIONS
The options documented in the following sections are specific to the raspistill utility, or commonly used with it. For full details of the other options (which are common to all the camera utilities), please refer to the raspicam(7) manual page.

GENERAL OPTIONS

-?, --help
    Display a concise description of all parameters

-bm, --burst
    Sets burst capture mode. This prevents the camera from returning to preview mode in between captures, meaning that captures can be taken closer together.

-d, --demo [ms]
    This options cycles through the range of camera options. No capture is taken, and the demo will end at the end of the timeout period, irrespective of whether all the options have been cycled. The time between cycles should be specified as a millisecond value.

-e, --encoding format
    Valid options are jpg (default), bmp, gif, and png. Note that only the JPEG format (-e jpg) is hardware accelerated. All other image types will take much longer to save. Also note that the filename suffix is completely ignored when deciding the encoding of a file.

-x, --exif key=value
    Allows the insertion of specific EXIF tags into the JPEG image. You can have up to 32 EXIF tag entries. This is useful for tasks like adding GPS metadata. For example, to set the longitude:

        --exif GPS.GPSLongitude=5/1,10/1,15/1

    would set the longitude to 5 degs, 10 minutes, 15 seconds. See [EXIF] documentation for more details on the range of tags available; the supported tags are as follows:

    IFD0.
    IFD1.
        ImageWidth, ImageLength, BitsPerSample, Compression, PhotometricInterpretation, ImageDescription, Make, Model, StripOffsets, Orientation, SamplesPerPixel, RowsPerString, StripByteCounts, XResolution, YResolution, PlanarConfiguration, ResolutionUnit, TransferFunction, Software, DateTime, Artist, WhitePoint, PrimaryChromaticities, JPEGInterchangeFormat, JPEGInterchangeFormatLength, YCbCrCoefficients, YCbCrSubSampling, YCbCrPositioning, ReferenceBlackWhite, Copyright

    EXIF.
        ExposureTime, FNumber, ExposureProgram, SpectralSensitivity, ISOSpeedRatings, OECF, ExifVersion, DateTimeOriginal, DateTimeDigitized, ComponentsConfiguration, CompressedBitsPerPixel, ShutterSpeedValue, ApertureValue, BrightnessValue, ExposureBiasValue, MaxApertureValue, SubjectDistance, MeteringMode, LightSource, Flash, FocalLength, SubjectArea, MakerNote, UserComment, SubSecTime, SubSecTimeOriginal, SubSecTimeDigitized, FlashpixVersion, ColorSpace, PixelXDimension, PixelYDimension, RelatedSoundFile, FlashEnergy, SpatialFrequencyResponse, FocalPlaneXResolution, FocalPlaneYResolution, FocalPlaneResolutionUnit, SubjectLocation, ExposureIndex, SensingMethod, FileSource, SceneType, CFAPattern, CustomRendered, ExposureMode, WhiteBalance, DigitalZoomRatio, FocalLengthIn35mmFilm, SceneCaptureType, GainControl, Contrast, Saturation, Sharpness, DeviceSettingDescription, SubjectDistanceRange, ImageUniqueID

    GPS.
        GPSVersionID, GPSLatitudeRef, GPSLatitude, GPSLongitudeRef, GPSLongitude, GPSAltitudeRef, GPSAltitude, GPSTimeStamp, GPSSatellites, GPSStatus, GPSMeasureMode, GPSDOP, GPSSpeedRef, GPSSpeed, GPSTrackRef, GPSTrack, GPSImgDirectionRef, GPSImgDirection, GPSMapDatum, GPSDestLatitudeRef, GPSDestLatitude, GPSDestLongitudeRef, GPSDestLongitude, GPSDestBearingRef, GPSDestBearing, GPSDestDistanceRef, GPSDestDistance, GPSProcessingMethod, GPSAreaInformation, GPSDateStamp, GPSDifferential

    EINT.
        InteroperabilityIndex, InteroperabilityVersion, RelatedImageFileFormat, RelatedImageWidth, RelatedImageLength

-fp, --fullpreview
    This runs the preview using the full resolution capture mode. Maximum frames per second in this mode is 15fps, and the preview will have the same field of view as the capture. Captures should happen more quickly, as no mode change should be required. This feature is currently under development.

-h, --height size
    Set the image height to size.

-k, --keypress
    The camera is run for the requested time (-t), and a capture can be initiated throughout that time by pressing the Enter key. Pressing X then Enter will exit the application before the timeout is reached. If the timeout is set to 0, the camera will run indefinitely until the user presses X then Enter. Using the verbose option (-v) will display a prompt asking for user input, otherwise no prompt is displayed.

-l, --latest filename
    Makes a file system link under this name to the latest frame.

-o, --output filename
    Specifies the output filename. If not specified, no file is saved. If the filename is “-”, then all output is send to stdout.

-q, --quality value
    Sets the JPEG compression quality from 0 to 100. 100 is nearly uncompressed, 75 is a good all-round value.

-r, --raw
    This option inserts the raw Bayer data from the camera into the JPEG metadata.

-rs, --restart num
    Sets the JPEG restart marker interval to a specific value. Can be useful for lossy transport streams because it allows a broken JPEG file to still be partially displayed.

-s, --signal
    The camera is run for the requested time (-t), and a capture can be initiated throughout that time by sending a USR1 signal to the camera process. This can be done using the killall(1) command. For example:

        killall -USR1 raspistill

-th, --thumb x:y:q
    Allows specification of the thumbnail image inserted into the JPEG file. If not specified, defaults are a size of 64x48 at quality 35. If --thumb none is specified, no thumbnail information will be placed in the file. This reduces the file size slightly.

-t, --timeout ms
    The program will run for the specified length of time, in milliseconds. It then takes the capture and saves it if an output is specified. If a timeout value is not specified, then it is set to 5 seconds (-t 5000). Note that low values (less than 500ms, although it can depend on other settings) may not give enough time for the camera to start up and provide enough frames for the automatic algorithms like AWB and AGC to provide accurate results. If set to 0, the preview will run indefinitely, until stopped with Ctrl-C. In this case no capture is made.

-v, --verbose
    Outputs debugging/information messages during the program run.

-w, --width size
    Set the image width to size.

TIMELAPSE OPTIONS

-tl, --timelapse ms
    The specific value is the time between shots in milliseconds. Note that you should specify %04d at the point in the filename where you want a frame count number to appear. So, for example, the code below will produce a capture every 2 seconds, over a total period of 30s, named “image0001.jpg”, “image0002.jpg” and so on, through to “image0015.jpg”:

        -t 30000 -tl 2000 -o image%04d.jpg

    Note that the %04d indicates a 4-digit number, with leading zeroes added to make the required number of digits. So, for example, %08d would result in an 8-digit number. If a timelapse value of 0 is entered, the application will take pictures as fast as possible. Note that there's an minimum enforced pause of 30ms between captures to ensure that exposure calculations can be made.

-dt, --datetime
    Instead of a simple frame number, the timelapse (-tl) filenames will use a date/time value of the format mmddHHMMSS, where mm is the month, dd is the day of the month, HH is the hour, MM is the minute, and SS is the second.

-fr, --framestart num
    Specifies the first frame number in the timelapse (-tl). Useful if you have already saved a number of frames, and want to start again at the next frame.

-ts, --timestamp
    Instead of a simple frame number, the timelapse (-tl) file names will use a single number which is the Unix timestamp, i.e. the seconds since 1970.

GL OPTIONS

-g, --gl
    Draw preview to texture instead of using video render component.

-gc, --glcapture
    Capture the GL frame-buffer instead of the camera image.

-gs, --glscene scene
    Select the GL scene which can be square, teapot, mirror, yuv, sobel, or vcsm_square.

-gw, --glwin x,y,w,h
    Specifies the GL window settings as an x,y location and a width and height.

EXIT STATUS

0   Application ran successfully (EX_OK)

64  Bad command line parameter (EX_USAGE)

70  Software or camera error (EX_SOFTWARE)

130 Application terminated by Ctrl-C

EXAMPLES
By default, captures are done at the highest resolution supported by the sensor. This can be changed using the -w and -h command line options.

raspistill -t 2000 -o image.jpg
    Take a default capture after 2s (times are specified in milliseconds) on the viewfinder, saving in image.jpg.

raspistill -t 2000 -o image.jpg -w 640 -h 480
    Take a capture at a different resolution.

raspistill -t 2000 -o image.jpg -q 5
    Reduce the quality considerably to reduce file size.

raspistill -t 2000 -o image.jpg -p 100,100,300,200
    Force the preview to appear at coordinate 100,100, with width 300 pixels and height 200 pixels.

raspistill -t 2000 -o image.jpg -n
    Disable the preview entirely.

raspistill -t 2000 -o image.png –e png
    Save the image as a PNG file (lossless compression, but slower than JPEG). Note that the filename suffix is ignored when choosing the image encoding.

raspistill -t 2000 -o image.jpg -x IFD0.Artist=Boris -x GPS.GPSAltitude=1235/10
    Add some EXIF information to the JPEG. This sets the Artist tag name to Boris, and the GPS altitude to 123.5m. Note that if setting GPS tags you should set as a minimum GPSLatitude, GPSLatitudeRef, GPSLongitude, GPSLongitudeRef, GPSAltitude, and GPSAltitudeRef.

raspistill -t 2000 -o image.jpg -ifx emboss
    Set an emboss image effect.

raspistill -t 2000 -o image.jpg -cfx 128:128
    Set the U and V channels of the YUV image to specific values (128:128 produces a greyscale image).

raspistill -t 2000
    Run preview for 2s, with no saved image.

raspistill -t 600000 -tl 10000 -o image_num_%03d_today.jpg -l latest.jpg
    Take a time-lapse picture, every 10 seconds for 10 minutes (10 minutes = 600000ms), naming the files “image_num_001_today.jpg”, “image_num_002_today.jpg” and so on, with the latest picture also available under the name “latest.jpg”.

raspistill -t 2000 -o -
    Take a picture and send the image data to stdout.

raspistill -t 2000 -o - > my_file.jpg
    Take a picture and send the image data to a file.

raspistill -t 0 -k -o my_pics%02d.jpg
    Run the camera forever, taking a picture when Enter is pressed.

SEE ALSO
raspicam(7), raspivid(1), raspividyuv(1), raspiyuv(1), vcgencmd(1), [SOURCE]

REFERENCES

[EXIF]
    https://en.wikipedia.org/wiki/Exif

[SOURCE]
    https://www.raspberrypi.org/documentation/raspbian/applications/camera.md