RaspiCam Documentation

======================
This document describes the use of the three Raspberry Pi camera applications as
of May 2013.
There are three applications proided! raspistill! raspiid and raspistillyu.
raspistill and raspistillyu are ery similar and are intended for capturin"
ima"es! raspiid is for capturin" ideo.
#ll the applications are command line drien! $ritten to ta%e adanta"e of the
mmal #P& $hich runs oer 'penM#(. The mmal #P& proides an easier to use system
than that presented by 'penM#(. )ote that mmal is a *roadcom specific #P& used
only on +ideocore , systems.
The applications use up to three 'penM#(-mmal. components / camera! preie$ and
encoder. #ll applications use the camera component! raspistill uses the &ma"e
0ncode component! raspiid uses the +ideo 0ncode component and raspistillyu
does not use an encoder! and sends its 12+ output direct from camera component
to file.
The preie$ display is optional! but can be used full screen or directed to a
specific rectan"ular area on the display.
&n addition it is possible to omit the filename option! in $hich case the
preie$ is displayed but no file is $ritten! or to redirect all output to
stdout.

Command line help is aailable by typin" 3ust the application name in on the
command line.
Common Command line 'ptions
===========================
Preie$ 4indo$
==============
//preie$! /p Preie$ $indo$ settin"s 567!y!$!h68
#llo$s the user to define the si9e and location on the screen that the preie$
$indo$ $ill be placed. )ote this $ill be superimposed oer the top of any other
$indo$s:"raphics.
//fullscreen! /f ;ullscreen preie$ mode
;orces the preie$ $indo$ to use the $hole screen. )ote that the aspect ratio of
the incomin" ima"e $ill be retained! so there may be bars on some ed"es.
//nopreie$! /n! Do not display a preie$ $indo$
Disables the preie$ $indo$ completely. )ote that een thou"h the preie$ is
disabled! the camera $ill still be producin" frames! so $ill be usin" po$er.
Camera Control 'ptions
======================
//sharpness! /sh <et ima"e sharpness -/100 to 100.
<et the sharpness of the ima"e! 0 is the default.
//contrast! /co <et ima"e contrast -/100 to 100.
<et the contrast of the ima"e! 0 is the default
//bri"htness! /br <et ima"e bri"htness -0 to 100.
<et the bri"htness of the ima"e! =0 is the default. 0 is blac%! 100 is $hite.
//saturation! /sa <et ima"e saturation -/100 to 100.
set the colour saturation of the ima"e. 0 is the default.
//&<'! /&<' <et capture &<'
)ot yet implemented
//stab! /s Turn on ideo stabilisation
&n ideo mode only! turn on ideo stabilisation.
//e! /e <et 0+ compensation
<et the 0+ compensation of the ima"e. Ran"e is /10 to >10! default is 0.
//e7posure! /e7 <et e7posure mode
Possible options are?
off
auto 2se automatic e7posure mode
ni"ht <elect settin" for ni"ht shootin"
ni"htpreie$
bac%li"ht <elect settin" for bac% lit sub3ect
spotli"ht
sports <elect settin" for sports -fast shutter etc.
sno$ <elect settin" optimised for sno$y scenery
beach <elect settin" optimised for beach
erylon" <elect settin" for lon" e7posures
fi7edfps! Constrain fps to a fi7ed alue
antisha%e #ntisha%e mode
fire$or%s <elect settin"s
)ote that not all of these settin"s may be implemented! dependin" on camera
tunin".
//a$b! /a$b <et #utomatic 4hite *alance -#4*. mode
off Turn off $hite balance calculation
auto #utomatic mode -default.
sun <unny mode
cloud Cloudy mode
shade <haded mode
tun"sten Tun"sten li"htin" mode
fluorescent ;luorescent li"htin" mode
incandescent &ncandescent li"htin" mode
flash ;lash mode
hori9on @ori9on mode
//im7f7! /if7 <et ima"e effect
<et an effect to be applied to the ima"e
none )' effect -default.
ne"atie )e"ate the ima"e
solarise <olarise the ima"e
posteri9e Posterise the ima"e
$hiteboard 4hiteboard effect
blac%board *lac%board effect
s%etch <%etch style effect
denoise Denoise the ima"e
emboss 0mboss the ima"e
oilpaint #pply an oil paint style effect
hatch @atch s%etch style
"pen
pastel # pastel style effect
$atercolour # $atercolour style effect
film ;ilm "rain style effect
blur *lur the ima"e
saturation Colour saturate the ima"e
colours$ap )ot fully implemented
$ashedout )ot fully implemented
posterise )ot fully implemented
colourpoint )ot fully implemented
colourbalance )ot fully implemented
cartoon )ot fully implemented
//colf7! /cf7 <et colour effect 52?+8
The supplied 2 and + parameters -ran"e 0 to 2==. are applied to the 2 and 1
channels of the ima"e. ;or e7ample! //colf7 12A?12A should result in a
monochrome ima"e.
//meterin"! /mm <et meterin" mode
<pecify the meterin" mode used for the preie$ and capture
aera"e #era"e the $hole frame for meterin".
spot <pot meterin"
bac%lit #ssume a bac%lit ima"e
matri7 Matri7 meterin"
--rotation, -rot Set image rotation (0-359)
Sets the rotation of the image in viewfinder and resulting image. This can take
an value from 0 u!wards, "ut due to hardware constraints onl 0, 90, #$0 and
%&0 degree rotations are su!!orted.
--hfli!, -hf Set hori'ontal fli!
(li!s the !review and saved image hori'ontall.
--vfli!, -vf Set vertical fli!
(li!s the !review and saved image verticall.
#pplication specific settin"s
=============================
raspistill
==========
//$idth! /$ <et ima"e $idth 5si9e8
//hei"ht! /h <et ima"e hei"ht 5si9e8
//Buality! /B <et 3pe" Buality 50 to 1008
Cuality 100 is almost completely uncompressed. D= is a "ood all round alue
//ra$! /r #dd ra$ bayer data to 3pe" metadata
This option inserts the ra$ *ayer data from the camera in to the EP0F metadata
//output /o 'utput filename 5filename8.
<pecify the output filename. &f not specified! no file is saed. &f the filename
is 6/6! then all output is sent to stdout.
//erbose! / 'utput erbose information durin" run
'utputs debu""in":information messa"es durin" the pro"ram run.
//timeout! /t Time before ta%es picture and shuts do$n.
The pro"ram $ill run for this len"th of time! then ta%e the capture -if output
is specified.. &f not specified! this is set to = seconds
//timelapse!/tl Timelapse mode.
The specific alue is the time bet$een shots in milliseconds. )ote you should
specify Gd at the point in the filename $here you $ant a frame count number to
appear. e.".
/t 30000 /tl 2000 /o ima"eGd.3p"
$ill produce a capture eery 2 seconds! oer a total period of 30s! named
ima"e1.3p"! ima"e2.3p"..ima"e1=.3p".
//thumb! /th <et thumbnail parameters -7?y?Buality.
#llo$s specification of the thumbnail ima"e inserted in to the EP0F file. &f not
specified! defaults are a si9e of H,7,A at Buality 3=.
//demo! d Run a demo mode 5milliseconds8
This options cycles throu"h ran"e of camera options! no capture is done! the
demo $ill end at the end of the timeout period! irrespectie of $hether all the
options hae been cycled. The time bet$een cycles should be specified as a
millisecond alue.
//encodin"! /e 0ncodin" to use for output file
+alid options are 3p"! bmp! "if and pn". )ote that unaccelerated ima"e types
-"if! pn"! bmp. $ill ta%e much lon"er to sae than EPF $hich is hard$are
accelerated. #lso note that the filename suffi7 is completely i"nored $hen
encodin" a file.
//e7if! /7 0(&; ta" to apply to captures -format as 6%ey=alue6.
#llo$s the insertion of specific e7if ta"s in to the EP0F ima"e. 1ou can hae up
to 32 e7if t"e entries. This is useful for thin"s li%e addin" FP< metadata. ;or
e7ample! to set the Ion"itude
//e7if FP<.FP<Ion"itude==:1!10:1!1=:100
$ould set the Ion"itude to =de"s! 10 minutes! 1= seconds. <ee e7if documentation
for more details on the ran"e of ta"s aailableJ the supported ta"s are as
follo$s.
&;D0.5 or
&;D1.5
&ma"e4idth! &ma"eIen"th! *itsPer<ample! Compression! Photometric&nterpretation!
&ma"eDescription! Ma%e! Model! <trip'ffsets! 'rientation! <amplesPerPi7el!
Ro$sPer<trin"! <trip*yteCounts! (resolution! 1resolution! PlanarConfi"uration!
Resolution2nit! Transfer;unction! <oft$are! DateTime! #rtist! 4hitePoint!
PrimaryChromaticities! EP0F&nterchan"e;ormat! EP0F&nterchan"e;ormatIen"th!
1cbCrCoefficients! 1cbCr<ub<amplin"! 1cbCrPositionin"! Reference*lac%4hite!
Copyri"ht8
0(&;.5
07posureTime! ;)umber! 07posurePro"ram! <pectral<ensitiity! a
&<'<peedRatin"s! '0C;! 07if+ersion! DateTime'ri"inal! DateTimeDi"iti9ed!
ComponentsConfi"uration! Compressed*itsPerPi7el! <hutter<peed+alue!
#perture+alue! *ri"htness+alue! 07posure*ias+alue! Ma7#perture+alue!
<ub3ectDistance! Meterin"Mode! Ii"ht<ource! ;lash! ;ocalIen"th! <ub3ect#rea!
Ma%er)ote! 2serComment! <ub<ecTime! <ub<ecTime'ri"inal! <ub<ecTimeDi"iti9ed!
;lashpi7+ersion! Color<pace! Pi7el(Dimension! Pi7el1Dimension! Related<ound;ile!
;lash0ner"y! <pacial;reBuencyResponse! ;ocalPlane(Resolution!
;ocalPlane1Resolution! ;ocalPlaneResolution2nit! <ub3ectIocation! 07posure&nde7!
<ensin"Method! ;ile<ource! <ceneType! C;#Pattern! CustomRendered! 07posureMode!
4hite*alance! Di"italKoomRatio! ;ocalIen"th&n3=mm;ilm! <ceneCaptureType!
FainControl! Contrast! <aturation! <harpness! Deice<ettin"Description!
<ub3ectDistanceRan"e! &ma"e2niBue&D8
FP<.5
FP<+ersion&D! FP<IatitudeRef! FP<Iatitude! FP<Ion"itudeRef! FP<Ion"itude!
FP<#ltitudeRef! FP<#ltitude! FP<Time<tamp! FP<<atellites! FP<<tatus!
FP<MeasureMode! FP<D'P! FP<<peedRef! FP<<peed! FP<Trac%Ref! FP<Trac%!
FP<&m"DirectionRef! FP<&m"Direction! FP<MapDatum! FP<DestIatitudeRef!
FP<DestIatitude! FP<DestIon"itudeRef! FP<DestIon"itude! FP<Dest*earin"Ref!
FP<Dest*earin"! FP<DestDistanceRef! FP<DestDistance! FP<Processin"Method!
FP<#rea&nformation! FP<Date<tamp! FP<Differential8
0&)T.5
&nteroperability&nde7! &nteroperability+ersion! Related&ma"e;ile;ormat!
Related&ma"e4idth! Related&ma"eIen"th8
)ote that a small subset of these ta"s $ill be set automatically by the camera
system! but $ill be oerridden by any e7if options on the command line.
raspiid
========
//$idth! /$ <et ima"e $idth 5si9e8
4idth of resultin" ideo. This should be bet$een H, and 1L20.
//hei"ht! /h <et ima"e hei"ht 5si9e8
@ei"ht of resultin" ideo. This should be bet$een H, and 10A0.
//bitrate! /b <et bitrate.
2se bits per second! so 10M*its:s $ould be /b 10000000. ;or @2H,! 10A0p a hi"h
Buality bitrate $ould be 1=Mbits:s or more.
//output /o 'utput filename 5filename8.
<pecify the output filename. &f not specified! no file is saed. &f the filename
is 6/6! then all output is sent to stdout.
//erbose! / 'utput erbose information durin" run
'utputs debu""in":information messa"es durin" the pro"ram run.
//timeout! /t Time before ta%es picture and shuts do$n.
The pro"ram $ill run for this len"th of time! then ta%e the capture -if output
is specified.. &f not specified! this is set to =seconds
//demo! d Run a demo mode 5milliseconds8
This options cycles throu"h ran"e of camera options! no capture is done! the
demo $ill end at the end of the timeout period! irrespectie of $hether all the
options hae been cycled. The time bet$een cycles should be specified as a
millisecond alue.
//framerate! /fps <pecify the frames per second to record
#t present! the minimum frame rate allo$ed is 2fps! the ma7imum is 30fps. This
is li%ely to chan"e in the future.
//penc! /e Display preie$ ima"e MafterM encodin"
<$itch on an option to display the preie$ after compression. This $ill sho$ any
compression artefacts in the preie$ $indo$. &n normal operation! the preie$
$ill sho$ the camera output prior to bein" compressed. This option is not
"uaranteed to $or% in future releases.
07amples
========
<till captures
*y default! captures are done at the hi"hest resolution supported by the sensor.
This can be chan"ed usin" the /$ and /h command line options.
Ta%in" a default capture after 2s -note times are specified in milliseconds. on
ie$finder! sain" in ima"e.3p"
raspistill /t 2000 /o ima"e.3p"
Ta%e a capture at a different resolution.
raspistill /t 2000 /o ima"e.3p" /$ H,0 /h ,A0
)o$ reduce the Buality considerably to reduce file si9e
raspistill /t 2000 /o ima"e.3p" /B =
;orce the preie$ to appear at coordinate 100!100! $ith $idth 300 and hei"ht 200
pi7els.
raspistill /t 2000 /o ima"e.3p" /p 100!100!300!200
Disable preie$ entirely
raspistill /t 2000 /o ima"e.3p" /n
<ae the ima"e as a pn" file -lossless compression! but slo$er than EP0F.. )ote
that the filename suffi7 is i"nored $hen choosin" the ima"e encodin".
raspistill /t 2000 /o ima"e.pn" Ne pn"
#dd some 0(&; information to the EP0F. This sets the #rtist ta" name to *oris!
and the FP< altitude to 123.=m. )ote that if settin" FP< ta"s you should set as
a minimum GPSLatitude, GPSLatitudeRef, GPSLongitude, GPSLongitudeRef, GPSAltitude and
GPSAltitudeRef.
raspistill /t 2000 /o ima"e.3p" /7 &;D'.#rtist=*oris /7
FP<.FP<#ltitude=123=:10
<et an emboss style ima"e effect
raspistill /t 2000 /o ima"e.3p" /if7 emboss
<et the 2 and + channels of the 12+ ima"e to specific alues -12A?12A produces a
"reyscale ima"e.
raspistill /t 2000 /o ima"e.3p" /cf7 12A?12A
Run preie$ ')I1 for 2s! no saed ima"e.
raspistill /t 2000
Ta%e timelapse picture! one eery 10 seconds for 10 minutes -10 minutes =
H00000ms.! named ima"eOnumberO1Otoday.3p"! ima"eOnumberO2Otoday.3p" on$ards.
raspistill /t H00000 /tl 10000 /o ima"eOnumOGdOtoday.3p"
Ta%e a picture and send ima"e data to stdout
raspistill /t 2000 /o /
Ta%e a picture and send ima"e data to file
raspistill /t 2000 /o / 8 myOfile.3p"
+ideo Captures
&ma"e si9e and preie$ settin"s are the same as for stills capture. Default si9e
for ideo recordin" is 10A0p -1L20710A0.
Record a =s clip $ith default settin"s -10A0p30.
raspiid /t =000 /o ideo.h2H,
Record a =s clip at a specified bitrate -3.=M*its:s.
raspiid /t =000 /o ideo.h2H, /b 3=00000
Record a =s clip at a specified framerate -=fps.
raspiid /t =000 /o ideo.h2H, /f =
0ncode a =s camera stream and send ima"e data to stdout
raspiid /t =000 /o /
0ncode a =s camera stream and send ima"e data to file
raspiid /t =000 /o / 8 myOfile.h2H,